user manual

ManualsBrandsDialogic ManualsIP PhoneIP Phone Dialogic Global Call IP

Dialogic

Global Call IP

Technology Guide

November 2007

05-2239-009

Summary of content (604 pages)

PAGE 1
Dialogic® Global Call IP Technology Guide November 2007 05-2239-009
PAGE 2
Copyright © 2003-2007, Dialogic Corporation. All rights reserved.You may not reproduce this document in whole or in part without permission in writing from Dialogic Corportation. All contents of this document are furnished for informational use only and are subject to change without notice and do not represent a commitment on the part of Dialogic Corporation or its subsidiaries (“Dialogic”). Reasonable effort is made to ensure the accuracy of the information contained in the document.
PAGE 3
Contents Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 About This Publication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Applicability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 4
Contents 3.3 3.4 4 IP-Specific Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 4.1 4.2 4.3 4.4 4.5 4.6 4 3.2.2 Endpoint Behavior in H.450.2 Blind Call Transfers . . . . . . . . . . . . . . . . . . . . . . . . 57 3.2.3 Successful H.450.2 Blind Call Transfer Scenario . . . . . . . . . . . . . . . . . . . . . . . . . 59 3.2.4 Unsuccessful H.450.2 Blind Call Transfer Scenarios . . . . . . . . . . . . . . . . . . . . . .
PAGE 5
Contents 4.7 4.8 4.9 4.10 4.11 4.12 4.13 4.14 4.15 4.6.1 Enabling and Disabling Unsolicited Notification Events . . . . . . . . . . . . . . . . . . . 4.6.2 Getting Media Streaming Status and Connection Information . . . . . . . . . . . . . . 4.6.3 Getting Notification of Underlying Protocol State Changes . . . . . . . . . . . . . . . . Modifying an Existing SIP Call via re-INVITE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.7.1 Overview of the SIP re-INVITE Method . . . . . .
PAGE 6
Contents 4.16 4.17 4.18 4.19 4.20 4.21 4.22 4.23 4.24 4.25 4.26 6 4.15.5 Sending NOTIFY Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 4.15.6 Receiving Responses to NOTIFY Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 4.15.7 Receiving NOTIFY Requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 4.15.8 Responding to NOTIFY Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 7
Contents 4.27 4.28 4.29 4.30 5 5.2 5.3 5.4 5.5 323 325 325 326 328 329 330 330 330 331 332 333 335 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1.1 Third Party Call Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.1.2 Global Call Library and IP Media Library for Third Party Call Control. . . . . . . . . 5.1.3 Session Description Protocol . . . . . . . . . . . . . . .
PAGE 8
Contents 7.2 8 IP-Specific Function Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 8.1 8.2 8.3 8 Configuring the Logging Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 7.2.1 Configuration File Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 7.2.2 Configuring the gc_h3r Logging Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 9
Contents 8.4 8.5 9 494 495 495 495 IP-Specific Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499 9.1 9.2 10 8.3.28 gc_Stop( ) Variances for IP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.3.29 gc_UnListen( ) Variances for IP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dialogic® Global Call API States Supported by IP. . . . . . . . . . . . . . . . . . . . . . . .
PAGE 10
Contents IP_REGISTER_ADDRESS – gatekeeper registration information . . . . . . . . . . . . . . . . . . 550 IP_TUNNELPROTOCOL_ALTID – TSM protocol alternate ID. . . . . . . . . . . . . . . . . . . . . 551 IP_TUNNELPROTOCOL_OBJECTID – tunneled signaling protocol object ID . . . . . . . . 552 IP_VIRTBOARD – information about an IPT board device . . . . . . . . . . . . . . . . . . . . . . . 553 IPCCLIB_START_DATA – IP call control library configuration information . . . . . . . . . . .
PAGE 11
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 Typical H.323 Network. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 H.323 Protocol Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Basic H.323 Network with a Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 12
Contents 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 12 SIP Call Transfer Failure - Party C is Busy When Transfer Attempted . . . . . . . . . . . . . . . . . . . 96 Sending T.38 Fax in an Established Audio Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Receiving T.38 Fax in an Established Audio Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Sending T.
PAGE 13
Contents Tables 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 41 Summary of Call-Related Information that can be Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Coders Supported for Dialogic® Host Media Processing (HMP) Software . . . . . . . . . . . . . . . Capabilities Set by Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Retrievable Call Information . . . . . . .
PAGE 14
Contents 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 14 Summary of Parameter Sets and Parameter Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499 GCSET_CALL_CONFIG Parameter Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511 IPSET_CALLINFO Parameter Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512 IPSET_CONFERENCE Parameter Set . . . . . . . .
PAGE 15
Revision History This revision history summarizes the changes made in each published version of this document. Document No. Publication Date Description of Revisions 05-2239-009 November 2007 Made global changes to reflect Dialogic brand. 05-2239-008 August 2006 Setting Coder Information: Added G.726 coder info SIP Rejection Responses: New section Using H.
PAGE 16
Revision History Document No. 05-2239-007 (continued) Publication Date Description of Revisions Retrieving SIP Message Header Fields section: Added note on truncation of too-long header fields Sending Nonstandard Protocol Messages (H.323): Updated for NS data >255 bytes Using MIME Bodies in SIP Messages (SIP-T) section: Updated for MIME header field parameters >255 bytes Using H.323 Annex M Tunneled Signaling Messages section: Updated for NS data >255 bytes. Updated defines for object IDs.
PAGE 17
Revision History Document No. Publication Date Description of Revisions 05-2239-006 August 2005 Call Control Library Initialization section: Expanded information on items that can be configured, including 3PCC mode Fast Start and Slow Start Call Setup section: Added subsections with H.323 and SIP specifics and notes on non-support in 3PCC mode H.323 Fast Start with Optional H.
PAGE 18
Revision History Document No.
PAGE 19
Revision History Document No. Publication Date 05-2239-005 (continued) Description of Revisions IPSET_TUNNELEDSIGNALMSG parameter set: New section GC_PARM_DATA_EXT data structure: New section IP_AUTHENTICATION data structure: New section IP_TUNNELPROTOCOL_ALTID data structure: New section IP_VIRTBOARD data structure: Added new h323_msginfo_mask value for Annex M tunneled signaling messages. Added sip_registration_registrar field.
PAGE 20
Revision History Document No.
PAGE 21
Revision History Document No. Publication Date Description of Revisions 05-2239-003 September 2004 General Conditions for Call Transfers section: New section Using Fast Start and Slow Start Setup section: Added note about H.323 fast start when no coder is specified (PTR#33321) Summary of Call-Related Information that can be Set table: Added note that GC_SINGLECALL must be used for Call ID and SIP Message Information fields. Added entries for four additional SIP Message Information fields.
PAGE 22
Revision History Document No. Publication Date Description of Revisions 05-2239-002 April 2004 Summary of Call-Related Information that can be Set table: Added entries for Call ID, MediaWaitForConnect, and PresentationIndicator. Coders Supported for Host Media Processing (HMP) table: Corrected G.711 entries to indicate VAD must be disabled (PTR 32576). Added row for G.729a. Corrected frame size for G.729a+b. Added row for T.38. (PTR 32623) Setting Busy Reason Codes: New section.
PAGE 23
Revision History Document No. Publication Date 05-2239-002 (continued) Description of Revisions IPADDR structure description: Added note that only supported ipv4 field value is IP_CFG_DEFAULT. Added info about byte order for IPv4 addresses. IPCCLIB_START_DATA structure description: Updated to refer to INIT_ IPCCLIB_START_DATA() initialization function.
PAGE 24
Revision History 24 Dialogic® Global Call IP Technology Guide — November 2007 Dialogic Corporation
PAGE 25
About This Publication The following topics provide information about this publication. • Purpose • Applicability • Intended Audience • How to Use This Publication • Related Information Purpose This publication documents the Dialogic® Global Call API for IP technology as it is implemented in Dialogic® Host Media Processing Software Release 3.1LIN. The Dialogic® Global Call API implementation in Dialogic® System Release software is documented in a separate set of documents.
PAGE 26
About This Publication • Original Equipment Manufacturers (OEMs) This publication assumes that the audience is familiar with the Windows® operating system and has experience using the C programming language. How to Use This Publication This guide is divided into the following chapters: • Chapter 1, “IP Overview”, gives a overview of VoIP technology and brief introductions to the H.323 and SIP standards for novice users.
PAGE 27
About This Publication • http://www.dialogic.
PAGE 28
About This Publication 28 Dialogic® Global Call IP Technology Guide — November 2007 Dialogic Corporation
PAGE 29
IP Overview 1. 1 This chapter provides overview information about the following topics: • Introduction to VoIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 • H.323 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 • SIP Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 1.
PAGE 30
IP Overview 1.2.1 H.323 Entities The H.323 specification defines the entity types in an H.323 network including: Terminal An endpoint on an IP network that supports the real-time, two-way communication with another H.323 entity. A terminal supports multimedia coders/decoders (codecs) and setup and control signaling. Gateway Provides the interface between a packet-based network (for example, an IP network) and a circuit-switched network (for example, the PSTN).
PAGE 31
IP Overview 1.2.2 H.323 Protocol Stack The H.323 specification is an umbrella specification for the many different protocols that comprise the overall H.323 protocol stack. Figure 2 shows the H.323 protocol stack. Figure 2. H.323 Protocol Stack Application H.245 (Logical Channel Signaling) H.225.0 (Q.931 Call Signaling) RTCP (Monitoring and QoS) H.255.0 (RAS) TCP Audio Codecs G.711, G.723.1, G.726, G.729, etc.
PAGE 32
IP Overview The RTP and RTCP combination is for media handling only. As indicated in Figure 2, the media part of the H.323 protocol is carried over UDP and therefore there is no guarantee that all packets will arrive at the destination and be placed in the correct order. 1.2.3 Codecs RTP and RTCP data is the payload of a User Datagram Protocol (UDP) packet. Analog signals coming from an endpoint are converted into the payload of UDP packets by codecs (coders/decoders).
PAGE 33
IP Overview Call Setup Establishing a call between two endpoints nominally requires two TCP connections between the endpoints: • one TCP connection for the call setup (Q.931/H.225 messages) • one TCP connection for capability exchange and call control (H.245 messages) In practice, the H.245 channel may not be required thanks to two additional features of the H.323 protocol. H.
PAGE 34
IP Overview • Connect This connection remains active for the entire duration of the call. The control channel is unique for each call between endpoints so that several different media streams can be present. An H.245 TerminalCapabilitySet message that includes information about the codecs supported by that endpoint is sent from one endpoint to the other.
PAGE 35
IP Overview EndSessionCommand, waits until it receives the same message from endpoint B, then closes the channel. Either endpoint (but typically the endpoint that initiates the termination) then sends an H.225.0 ReleaseComplete message over the call signalling channel, which closes that channel and ends the call. 1.2.5 Registration with a Gatekeeper In a H.323 network, a gatekeeper is an entity that can manage all endpoints that can send or receive calls.
PAGE 36
IP Overview Endpoint Registration An endpoint uses a process called registration to join the zone associated with a gatekeeper. In the registration process, the endpoint informs the gatekeeper of its transport, alias addresses, and endpoint type. Endpoints register with the gatekeeper identified in the gatekeeper discovery process described above. Registration can occur before any calls are made or periodically as necessary.
PAGE 37
IP Overview A gateway provides a bridge between different technologies; for example, an H.323 gateway (or IP gateway) provides a bridge between an IP network and the PSTN. Figure 3 shows a configuration that uses a gateway. User A is at a terminal, while user B is by a phone connected to the PSTN. Figure 3. Basic H.323 Network with a Gateway User B User A PSTN Terminal Phone Gateway Gatekeeper Internet or Intranet Figure 3 also shows a gatekeeper.
PAGE 38
IP Overview • the type of call; in this case, point-to-point • the call model to use, either direct or gatekeeper-routed • the destination address; in this case, the phone number of endpoint B • an estimation of the amount of bandwidth required. This parameter can be adjusted later by a Bandwidth Request (BRQ) message to the gatekeeper. If the gatekeeper allows the call to proceed, it sends an Admission Confirm (ACF) message to endpoint A.
PAGE 39
IP Overview When all channels between endpoint A and the gateway are closed, each must send a DisengageRequest (DRQ) message to the gatekeeper. This message lets the gatekeeper know that the bandwidth is being released. The gatekeeper sends a DisengageConfirm (DCF) message to both endpoint A and the gateway. 1.3 SIP Overview Session Initiation Protocol (SIP) is an ASCII-based, peer-to-peer protocol designed to provide telephony services over the Internet.
PAGE 40
IP Overview Redirect Server Accepts a request from a client and maps the address to zero or more new addresses and returns the new addresses to the client. The server does not accept calls or generate SIP requests on behalf of clients. Registrar Server Accepts REGISTER requests from clients. Often, the registrar server is located on the same physical server as the proxy server or redirect server. 1.3.3 Basic SIP Operation Callers and callees are identified by SIP addresses.
PAGE 41
IP Overview SIP Request Messages The most commonly used SIP request messages are: • INVITE • ACK • BYE • REGISTER • CANCEL • OPTIONS For more information on specific SIP request types, see RFC 3261 at http://ietf.org/rfc/rfc3261.txt. SIP Response Messages SIP response messages are numbered. The first digit in each response number indicates the type of response.
PAGE 42
IP Overview 42 Dialogic® Global Call IP Technology Guide — November 2007 Dialogic Corporation
PAGE 43
Dialogic® Global Call API Architecture for IP 2. 2 This chapter discusses the following topics: • Dialogic® Global Call API over IP Architecture with a Host-Based Stack . . . . . . . . . 43 • Architecture Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 • Device Types and Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 2.
PAGE 44
Dialogic® Global Call API Architecture for IP Figure 5. Dialogic® Global Call API Over IP Architecture Host Application GlobalCall Media Routing Call Control Signaling IP Network Host NIC H.
PAGE 45
Dialogic® Global Call API Architecture for IP 2.2.1 Host Application The host application manages and monitors the IP telephony system operations.
PAGE 46
Dialogic® Global Call API Architecture for IP 2.2.4 IP Media Call Control Library (IPM CCLib) The IP Media Call Control Library (IPM CCLib) performs the following tasks: • processes Dialogic® Global Call API CCLib commands for the opening, closing, and timeslot routing of IP media devices • configures QoS (Quality of Service) thresholds • translates QoS alarm events to Dialogic® Global Call API alarm (GCAMS) events 2.2.5 IP Media Resource The IP Media Resource processes the IP Media stream.
PAGE 47
Dialogic® Global Call API Architecture for IP The IPT network device (iptBxTy) and the IP Media device (ipmBxCy) can be opened simultaneously in the same gc_OpenEx( ) command. If a voice resource is available in the system, for example an IP board that provides voice resources or any other type of board that provides voice resources, a voice device can also be included in the same gc_OpenEx( ) call to provide voice capabilities on the logical channel. See Section 8.3.
PAGE 48
Dialogic® Global Call API Architecture for IP opened simultaneously, etc. See Section 8.3.27, “gc_Start( ) Variances for IP”, on page 491 for more information on how to configure IPT board devices. Figure 7. Configurations for Binding IPT Boards to NIC IP Addresses A. Multiple IP Addresses Assigned to the Same Host NIC B.
PAGE 49
Dialogic® Global Call API Architecture for IP • SIP only (P_SIP in the devicename string when opening the device) • Dual protocol, H.323 and SIP (P_IP in the devicename string when opening the device) The device type is determined when using the gc_OpenEx( ) function to open the device. H.323 and SIP only devices are capable of initiating and receiving calls of the selected protocol type only. Dual protocol devices are capable of initiating and receiving calls using either the H.323 or SIP protocol.
PAGE 50
Dialogic® Global Call API Architecture for IP 50 Dialogic® Global Call IP Technology Guide — November 2007 Dialogic Corporation
PAGE 51
IP-Specific Operations 4. 4 This chapter describes how to use the Dialogic® Global Call API to perform certain operations in an IP environment. These operations include: • Call Control Library Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 • Fast and Slow Call Setup Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 • Setting Call-Related Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 52
IP-Specific Operations • LAN Disconnection Alarms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333 • Setting Dialogic® IP Media Library Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 4.1 Call Control Library Initialization Certain system parameters are configurable when using the gc_Start( ) function to initialize the Dialogic® Global Call API library.
PAGE 53
IP-Specific Operations For details on the overall configuration process, including the default values and the allowable values that can be set for each configuration item, see Section 8.3.27, “gc_Start( ) Variances for IP”, on page 491, the reference page for IP_VIRTBOARD on page 553, and the reference page for IPCCLIB_START_DATA on page 558.
PAGE 54
IP-Specific Operations 4.1.2 Configuring SIP Transport Protocol When initializing a board device for use with SIP, the application can enable the use of the TCP transport protocol in addition to the default UDP transport. When TCP is enabled, the Dialogic® Global Call API library listens for incoming TCP connections as well as UDP connections on the SIP signaling port that is configured for the board.
PAGE 55
IP-Specific Operations SIP_maxUDPmsgLen Sets a maximum size for UDP messages. If TCP is enabled and the application attempts to send a message by UDP that exceeds the configured maximum size (default is 1300 as suggested in RFC3261), TCP transport is automatically used rather than UDP. This size checking may have an undesirable effect on system performance, and a parameter value is defined which disables the feature.
PAGE 56
IP-Specific Operations // set outbound proxy by IP Address virtBoards[0].outbound_proxy_IP.ip_ver = IPVER4; virtBoards[0].outbound_proxy_IP.u_ipaddr.ipv4 = inet_addr("192.168.1.227"); // set outbound proxy port virtBoards[0].outbound_proxy_port = 5060; //enable and configure TCP for proxy virtBoards[0].E_SIP_tcpenabled = ENUM_Enabled; virtBoards[0].E_SIP_OutboundProxyTransport = ENUM_TCP; virtBoards[0].
PAGE 57
IP-Specific Operations Selected Requests UDP Parameter Value E_SIP_tcpenabled ENUM_Enabled E_SIP_OutboundProxyTransport not set E_SIP_Persistence ENUM_PERSISTENCE_TRANSACT_USER (default) SIP_maxUDPmsgLen not set E_SIP_DefaultTransport ENUM_TCP outbound_proxy_* fields IP and hostname both not set sip_msginfo_mask includes IP_SIP_MSGINFO_ENABLE transport parameter in Request-URI set to “;transport=udp” on selected requests Transport Parameter Combinations with Proxy All Requests UDP via Pro
PAGE 58
IP-Specific Operations Selected Requests TCP via Proxy Parameter Value E_SIP_tcpenabled ENUM_Enabled E_SIP_OutboundProxyTransport ENUM_UDP (default) E_SIP_Persistence ENUM_PERSISTENCE_TRANSACT_USER (default) SIP_maxUDPmsgLen 1300 (default) E_SIP_DefaultTransport not set outbound_proxy_ fields IP -or- hostname set sip_msginfo_mask includes IP_SIP_MSGINFO_ENABLE transport parameter in Request-URI set to “;transport=tcp” for selected requests Selected requests are sent TCP to the proxy, and
PAGE 59
IP-Specific Operations For incoming calls, tunneling is enabled by default, but it can be configured on a board device level (where a board device is a virtual entity that corresponds to a NIC or NIC address; see Section 2.3.2, “IPT Board Devices”, on page 47). This is done using the gc_SetConfigData( ) function with target ID of the board device and the parameters above specified in the GC_PARM_BLKP structure associated with the gc_SetConfigData( ) function. Note: 4.
PAGE 60
IP-Specific Operations The scope of the mode setting is determined by which Global Call function the application passes the GC_PARM_BLK to: • gc_SetConfigData( ) sets the slow start mode as the default for the entire system (all line devices on all board devices for both H.323 and SIP protocols). • gc_SetUserInfo( ) with duration = GC_ALLCALLS sets the slow start mode as the default connection mode for H.323 and SIP calls on a given line device.
PAGE 61
IP-Specific Operations Fast start connection, on the other hand, reduces the time required to set up a call to one round-trip of delay after the H.225 TCP connection is established by “piggy-backing” the local endpoint’s media capabilities and RTP port in the Q.931 Setup message in a “fastStart element”. If the remote side supports fast start connection, it returns the capability parameters in the Alerting, Proceeding, or Connect messages. Note: 4.2.3 In an H.
PAGE 62
IP-Specific Operations • gc_MakeCall( ) sets the specified H.245 mode for the new call only. When the application specifies that the H.245 channel is optional, channel establishment proceeds normally with the exchange of MSD and TCS messages and acknowledgements after the library has generated a GCEV_CONNECTED event to the application (assuming that the remote endpoint accepts fast start setup). The application can optionally receive notification of the status of H.
PAGE 63
IP-Specific Operations SIP uses the term delayed offer to refer to cases where the INVITE does not include the SDP offer, which corresponds to a “slow start” connection mode. When the calling party in a SIP call uses the default fast start setup mode, the SDP offer is included in the INVITE message that initiates the connection attempt. The remote party then sends an SDP answer in its 200 OK response.
PAGE 64
IP-Specific Operations The defined mask values that are used to enable access to fast start coder information are: IP_SIP_FASTSTART_CODERS_IN_OFFERED when OR’ed into the sip_msginfo_mask field, enables application access to coder information contained in SDP offers in SIP INVITE requests IP_H323_FASTSTART_CODERS_IN_OFFERED when OR’ed into the h323_msginfo_mask field, enables application access to coder information contained in fastStart elements in H.
PAGE 65
IP-Specific Operations When all of these conditions are true, the extra data associated with the GCEV_OFFERED event will be a GC_PARM_BLK that contains one or more parameter elements of the following type: IPSET_CALLINFO IPPARM_OFFERED_FASTSTART_CODER • value = IP_CAPABILITY data structure Each such parameter element reflects a coder specification that was contained in the call offer.
PAGE 66
IP-Specific Operations 4.3.1 Overview of Setting Call-Related Information Table 1 summarizes the types of information elements that can be specified, the corresponding set IDs and parameter IDs used to set the information, the functions that can be used to set the information, and an indication of whether the information is supported when using H.323, SIP, or both.
PAGE 67
IP-Specific Operations Table 1. Summary of Call-Related Information that can be Set (Continued) Type of Information MediaWaitFor Connect Set ID and Parameter IDs IPSET_CALLINFO • IPPARM_MEDIAWAITFORCONNECT Functions Used to Set Information SIP/ H.323 gc_SetUserInfo( ) (GC_SINGLECALL only) H.323 only gc_MakeCall( ) Nonstandard Control Information IPSET_NONSTANDARDCONTROL gc_SetConfigData( ) Either: gc_SetUserInfo( ) †† • IPPARM_NONSTANDARDDATA_DATA and IPPARM_NONSTANDARDDATA_OBJID H.
PAGE 68
IP-Specific Operations Table 1. Summary of Call-Related Information that can be Set (Continued) Type of Information Tunnelling††† Set ID and Parameter IDs IPSET_CALLINFO • IPPARM_H245TUNNELING Functions Used to Set Information gc_SetConfigData( ) gc_SetUserInfo( ) †† SIP/ H.323 H.
PAGE 69
IP-Specific Operations • Using gc_MakeCall( ) Setting Per-Call Call Parameters Using gc_SetUserInfo( ) The gc_SetUserInfo( ) function (with the duration parameter set to GC_SINGLECALL) can be used to set call parameter values for a single incoming call. This is useful since the gc_AnswerCall( ) function does not have a parameter to specify a GC_PARM_BLK. At the end of the call, the values set as defaults for the specified line device replace these call-specific values.
PAGE 70
IP-Specific Operations Possible values for fields in the IP_CAPABILITY structure are: capability Specifies the coder type from among the types supported by the particular IP telephony platform; see Table 2 for platform-specific coder types. The following values are defined for the capability field: • GCCAP_AUDIO_g711Alaw64k • GCCAP_AUDIO_g711Ulaw64k • GCCAP_AUDIO_g7231_5_3k (G.723.1 at 5.3 kbps) • GCCAP_AUDIO_g7231_6_3k (G.723.1 at 6.
PAGE 71
IP-Specific Operations See the reference page for IP_CAPABILITY on page 543 for more information. Table 2 shows the coders that are supported when using the Dialogic® Global Call API with Dialogic® Host Media Processing (HMP) Software. Table 2. Coders Supported for Dialogic® Host Media Processing (HMP) Software Coder and Rate Dialogic® Global Call API # Define G.
PAGE 72
IP-Specific Operations gc_AcceptCall( ) to get maximum benefit from Global Call’s early media support. Capability types can be GCCAPTYPE_AUDIO and/or GCCAPTYPE_RDATA. The session capabilities that can result when different capabilities are set by applications are listed in the Table 3. Table 3. Capabilities Set by Application 4.3.2.
PAGE 73
IP-Specific Operations parameter set ID. The first required parameter element specifies the Nonstandard Data itself, and the second parameter element identifies the type of object identifier to use. The maximum length of the Global Call parameter used for the Nonstandard Data information is configured at start-up via the max_parm_data_size field in the IPCCLIB_START_DATA structure. The default size is 255 (for backwards compatibility), but applications may configure it to be as large as 4096 bytes.
PAGE 74
IP-Specific Operations if (choiceOfNSData) /* App decides the CHOICE of OBJECTIDENTIFIER. It cannot set both objid & H221 */ { gc_util_insert_parm_ref(&pParmBlock, IPSET_NONSTANDARDDATA, IPPARM_H221NONSTANDARD, (unsigned char)sizeof(IP_H221NONSTANDARD), &appH221NonStd); } else { gc_util_insert_parm_ref(&pParmBlock, IPSET_NONSTANDARDDATA, IPPARM_NONSTANDARDDATA_OBJID, (unsigned char)(strlen(pOid)+1), pOid); } 4.3.4 Specifying Nonstandard Control Information (H.
PAGE 75
IP-Specific Operations IPSET_NONSTANDARDCONTROL IPPARM_H221NONSTANDARD • value = IP_H221NONSTANDARD structure See Section 9.2.17, “IPSET_NONSTANDARDCONTROL”, on page 525 for more information. The following code example shows how to set nonstandard data elements: IP_H221NONSTANDARD appH221NonStd; appH221NonStd.country_code = 181; appH221NonStd.extension = 31; appH221NonStd.
PAGE 76
IP-Specific Operations 4.4.1 Setting and Retrieving Disconnect Cause or Reason Values Use the cause parameter in the gc_DropCall( ) function to specify a disconnect reason/cause to be sent to the remote endpoint. Note: When using SIP, reasons are only supported when a call is disconnected while in the Offered state. Use the gc_ResultInfo( ) function to get the reason/cause of a GCEV_DISCONNECTED event.
PAGE 77
IP-Specific Operations By default, Global Call automatically responds with a 486 Busy Here when additional incoming call requests arrive after the maximum number of SIP calls per virtual board has been reached. A 480 Temporarily Unavailable or 600 Busy Everywhere reason code can be used instead of the 486 Busy Here if the application explicitly configures the busy code.
PAGE 78
IP-Specific Operations The following code snippet illustrates how to set the H.323 busy code: #include "gclib.h" . . /* configure H.
PAGE 79
IP-Specific Operations 4.4.3.1 Retrieving Status-Code for 18x Provisional Responses When using SIP, each GCEV_ALERTING event will have an associated GC_PARM_BLK that contains the specific status code for the 18x provisional response message in a parameter element of the following type: IPSET_SIP_RESPOSNSE_CODE IPPARM_RECEIVED_RESPONSE_STATUS_CODE • value = 3-digit integer retrieved as Status-Code from Status-Line of the received provisional message 4.4.3.
PAGE 80
IP-Specific Operations 4.4.4 SIP Redirection (3xx) Response Messages RFC 3261 defines the 3xx range of responses as redirection messages, which can be used by the called party’s server to push alternative routing information back to the originator of an INVITE request. This allows the server to provide information that is useful in locating the target of the request while also taking itself out of the loop for further messaging for the transaction.
PAGE 81
IP-Specific Operations • None of the URIs in the Contact header field can be equal to the one in the Request-URI. • For a 301 or 302, the response may contain the same location and username that was targeted in the original request, but additional transport parameters to try, such as a different multicast address or a different transport protocol. • A Contact header field can point to a different resource than the one originally called, and can use any suitable URI (not just SIP URIs).
PAGE 82
IP-Specific Operations Via: SIP/2.0/UDP 146.152.84.1:5060;received=146.152.84.2;branch=z9hG4bK-28795-9e19f19-554d9dc4 Supported: replaces Contact: "forward1" ;q=0.7;expires=3600,"forward2" ;q=0.5;expires=60 Content-Length: 0 4.4.4.2 Receiving and Handling a Redirect Response After receiving a GCEV_DISCONNECTED event, the application can check the cause of the event.
PAGE 83
IP-Specific Operations break; } break; } } } /* continue drop call on this channel */ . . . } . . .
PAGE 84
IP-Specific Operations if ( HeaderName != NULL && 0==_stricmp(HeaderName,"contact") && (HeaderData != NULL) && (HeaderDataSize != 0) ) { ptr = strchr(HeaderData,'<'); redirectURI=ptr+sizeof(char); ptr = strchr(HeaderData,'>'); ptr[0]='\0'; return redirectURI; } else { return NULL; } } 4.4.5 SIP Rejection Responses Note: The information in this section only applies when the Dialogic® Global Call IP Call Control library is started in the first party call control (1PCC) operating mode.
PAGE 85
IP-Specific Operations This alternative response to media session proposals is enabled using the gc_SetConfigData( ) function, passing it a GC_PARM_BLK that includes the following parameter: IPSET_CONFIG IPPARM_1PCC_REJECT_VIDEO • value = not used Once this alternative rejection mode has been enabled, the setting remains in effect until the library is stopped and the application exits.
PAGE 86
IP-Specific Operations 2. Use the gc_Extension( ) function to request the data. The parameters for this call should be specified as follows: • target_type should be GCTGT_GCLIB_CRN • target_id should be the actual CRN • ext_id (extension ID) should be set to IPEXTID_GETINFO • parmblkp should point to the GC_PARM_BLK set up in step 1 • mode should be set to EV_ASYNC (asynchronous) 3. A GCEV_EXTENSIONCMPLT event is generated in response to the gc_Extension( ) request.
PAGE 87
IP-Specific Operations Table 4. Retrievable Call Information Parameter Call ID Set ID and Parameter ID(s) IPSET_CALLINFO • IPPARM_CALLID When Information Can Be Retrieved Any state after Offered or Proceeding Datatype in value_buf Field (see Note 1) For SIP: string, max. length = MAX_IP_SIP_ CALLID_LENGTH SIP/ H.323 both For H.323: array of octets, length = MAX_IP_H323_ CALLID_LENGTH If protocol is unknown, MAX_IP_CALLID_ LENGTH defines the maximum Call ID length for any possible protocol.
PAGE 88
IP-Specific Operations Table 4. Retrievable Call Information (Continued) Parameter Set ID and Parameter ID(s) Nonstandard Control IPSET_NONSTANDARDCONTROL (see note 4) • IPPARM_ NONSTANDARDDATA_DATA and either • IPPARM_ NONSTANDARDDATA_OBJID or When Information Can Be Retrieved See Section 4.5.1, “Retrieving Nonstandard Data From Protocol Messages (H.323)”, on page 145 for more information.
PAGE 89
IP-Specific Operations will not contain the requested information. If phone list and display information are requested and only phone list is available, then only phone list information is available in the GC_PARM_BLK. An error is generated if there is an internal error (such as memory cannot be allocated). All call information is available until a gc_ReleaseCallEx( ) is issued. 4.5.1 Retrieving Nonstandard Data From Protocol Messages (H.323) Any received Q.931 message can include Nonstandard Data.
PAGE 90
IP-Specific Operations int getInfoAsync(CRN crn) { GC_PARM_BLKP gcParmBlk = NULL; GC_PARM_BLKP retParmBlk; int frc; frc = gc_util_insert_parm_val(&gcParmBlk, IPSET_CALLINFO, IPPARM_PHONELIST, sizeof(int),1); if (GC_SUCCESS != frc) { return GC_ERROR; } frc = gc_util_insert_parm_val(&gcParmBlk, IPSET_CALLINFO, IPPARM_CALLID, sizeof(int),1); if (GC_SUCCESS != frc) { return GC_ERROR; } frc = gc_util_insert_parm_val(&gcParmBlk, IPSET_CONFERENCE, IPPARM_CONFERENCE_ID, sizeof(int),1); if (GC_SUCCESS != frc) { ret
PAGE 91
IP-Specific Operations frc = gc_util_insert_parm_val(&gcParmBlk, IPSET_VENDORINFO, IPPARM_VENDOR_PRODUCT_ID, sizeof(int),1); if (GC_SUCCESS != frc) { return GC_ERROR; } frc = gc_util_insert_parm_val(&gcParmBlk, IPSET_VENDORINFO, IPPARM_VENDOR_VERSION_ID, sizeof(int),1); if (GC_SUCCESS != frc) { return GC_ERROR; } frc = gc_util_insert_parm_val(&gcParmBlk, IPSET_VENDORINFO, IPPARM_H221NONSTD, sizeof(int),1); if (GC_SUCCESS != frc) { return GC_ERROR; } frc = gc_util_insert_parm_val(&gcParmBlk,/* NS Data: sett
PAGE 92
IP-Specific Operations Extracting Call-Related Information Associated with an Extension Event The following code demonstrates how an application can extract call information when a GCEV_EXTENSIONCMPLT event is received as a result of a request for call-related information.
PAGE 93
IP-Specific Operations { printf("\tReceived extension data IPPARM_CONFERENCE_GOAL: %d\n", (unsigned int)(*(parmp->value_buf))); } break; case IPPARM_CONFERENCE_ID: if(parmp->value_size != 0) { printf("\tReceived extension data IPPARM_CONFERENCE_ID: %s\n", parmp->value_buf); } break; default: printf("\tReceived unknown CONFERENCE extension parmID %d\n", parmp->parm_ID); break; } break; case IPSET_VENDORINFO: switch (parmp->parm_ID) { case IPPARM_VENDOR_PRODUCT_ID: if(parmp->value_size != 0) { printf("\tRece
PAGE 94
IP-Specific Operations case IPPARM_NONSTANDARDDATA_OBJID: printf("\tReceived extension data (NSDATA) OBJID: %s\n", parmp->value_buf); break; case IPPARM_H221NONSTANDARD: { if(parmp->value_size == sizeof(IP_H221NONSTANDARD)) { IP_H221NONSTANDARD *pH221NonStandard; pH221NonStandard = (IP_H221NONSTANDARD *)(&(parmp->value_buf)); printf("\tReceived extension data (NSDATA) h221:CC=%d, Ext=%d, MC=%d\n", pH221NonStandard->country_code, pH221NonStandard->extension, pH221NonStandard->manufacturer_code); } } break;
PAGE 95
IP-Specific Operations case IPSET_MSG_Q931: switch (parmp->parm_ID) { case IPPARM_MSGTYPE: switch ((*(int *)(parmp->value_buf))) { case IP_MSGTYPE_Q931_FACILITY: printf("\tReceived extension data IP_MSGTYPE_Q931_FACILITY\n"); break; default: printf("\tReceived unknown MSG_Q931 extension parmID %d\n", parmp->parm_ID); break; } /* end switch ((int)(parmp->value_buf)) */ break; }/* end switch (parmp->parm_ID) for IPSET_MSG_Q931 */ break; case IPSET_MSG_H245: switch (parmp->parm_ID) { case IPPARM_MSGTYPE: swit
PAGE 96
IP-Specific Operations #include #include #include #include #include /* * Assume the 'crn' parameter holds the CRN associated * with the detected GCEV_OFFERED event.
PAGE 97
IP-Specific Operations int print_call_info(CRN crn, METAEVENT *pEvt) { EXTENSIONEVTBLK *ext_data = NULL; GC_PARM_DATA *parmp = NULL; GC_PARM_BLK *parm_blkp; if (pEvt) { if (pEvt->evttype == GCEV_EXTENSIONCMPLT) { ext_data = (EXTENSIONEVTBLK *)(pEvt->extevtdatap); } } if (!ext_data) { printf("\tNot a GCEV_EXTENSIONCMPLT event.
PAGE 98
IP-Specific Operations 4.6 Receiving Notification Events Note: The information in this section only applies when the Dialogic® Global Call API IP call control library is started in the first party call control (1PCC) operating mode. The extension events that provides the capabilities described in this section are not supported when the library is started in the third party call control (3PCC) operating mode.
PAGE 99
IP-Specific Operations Possible values (corresponding to events that can be added or removed from the mask are) are: EXTENSIONEVT_DTMF_ALPHANUMERIC For notification of DTMF digits received in User Input Indication (UII) messages with alphanumeric data. When using SIP, this value is not applicable. EXTENSIONEVT_SIGNALING_STATUS For notification of intermediate protocol state changes in signaling (in H.323, for example, Q.931 Connected and Disconnected) and control (in H.323, for example, H.
PAGE 100
IP-Specific Operations • IPPARM_RX_RECVONLY – Media streaming has been initiated for a half-duplex receive-only connection. The parameter value is an IP_CAPABILITY structure containing the coder configuration that resulted from the capability exchange with the remote peer. • IPPARM_TX_INACTIVE – Media streaming in the transmit direction has been suspended. The parameter value is an IP_CAPABILITY structure containing the coder configuration that resulted from the capability exchange with the remote peer.
PAGE 101
IP-Specific Operations else { //only get tx or rx, not both l_pParmData = gc_util_find_parm(gcParmBlk, IPSET_MEDIA_STATE, IPPARM_RX_CONNECTED); if(l_pParmData != NULL) { memcpy(&l_IPCap, l_pParmData->value_buf, l_pParmData->value_size); } } } 4.6.3 Getting Notification of Underlying Protocol State Changes The application can receive notification of intermediate protocol signaling state changes for both H.323 and SIP. The events for this notification must be enabled; see Section 4.6.
PAGE 102
IP-Specific Operations • Receiving SIP re-INVITE Requests • Responding to SIP re-INVITE Requests • Sending a SIP re-INVITE Request • Canceling a Pending re-INVITE Request • Updating Dialog Properties via re-INVITE • Implementing Hold and Retrieve via SIP re-INVITE 4.7.1 Overview of the SIP re-INVITE Method RFC 3261 specifies that User Agents must be able to send and respond to additional INVITE requests after a dialog has been established to allow modification of the dialog or the media session.
PAGE 103
IP-Specific Operations • changing between audio and T.38 fax modes Note: The existing automatic and manual modes for audio/T.38 switching (as described in Section 4.26, “T.38 Fax Server”) have used re-INVITE “under the hood” when using the SIP protocol. But when an application has enabled access to re-INVITE requests, audio/T.38 fax mode changes must be handled explicitly by the application, just like any other re-INVITE requests. 4.7.
PAGE 104
IP-Specific Operations RFC3261 specifies that either party in a SIP dialog can initiate a re-INVITE transaction, so Global Call applications must be able to receive and handle incoming re-INVITE requests whenever application access to re-INVITE is enabled. When the IP Call Control Library receives a re-INVITE request, the library first examines the request to determine whether it specifies media properties that are acceptable by the local endpoint.
PAGE 105
IP-Specific Operations different from the current session properties, and to decide whether any proposed change is acceptable. The GC_PARM_BLOCK that is associated with the GCEV_REQ_MODIFY_CALL event may contain any number of parameter elements which identify the supported media properties that were proposed in the request.
PAGE 106
IP-Specific Operations There will always be at least one of these parameter elements if the re-INVITE request contains an SDP offer (which is the typical case for re-INVITE requests). Note: 4.7.4 SDP does not explicitly communicate RTCP port addresses, but these can be inferred from RTP addresses according to the “plus one” offset convention. Responding to SIP re-INVITE Requests This section focuses primarily on library behavior in 1PCC operating mode.
PAGE 107
IP-Specific Operations To formulate a specific SDP answer, an application inserts appropriate media capability parameter elements into the GC_PARM_BLK parameter block that it passes to gc_AcceptModifyCall( ). Each parameter element is of the following format: GCSET_CHAN_CAPABILITY IPPARM_LOCAL_CAPABILITY • value = IP_CAPABILITY data structure A full-duplex connection requires two such parameter elements, one for each direction.
PAGE 108
IP-Specific Operations The GC_PARM_BLK that the application constructs may contain three types of parameter elements. There may be an element to specify the DTMF mode, one or more elements to specify SIP header fields to change in order to update the properties of the dialog (such as the Contact or Via information), and one or more elements to specify media capabilities to be included in the SDP offer within the re-INVITE request. 4.7.5.
PAGE 109
IP-Specific Operations 4.7.5.3 Specifying Media Session Properties in a SIP re-INVITE If an application wishes to change any media session properties via a re-INVITE request, it must insert appropriate media capability parameter elements into the GC_PARM_BLK that it passes to gc_ReqModifyCall( ).
PAGE 110
IP-Specific Operations No other parameter elements can be present in the GC_PARM_BLK when canceling a re-INVITE request. 4.7.7 Updating Dialog Properties via re-INVITE Dialog properties that are specified in SIP message header fields can be updated or changed by sending a re-INVITE request that contains header fields with new values. The most common use of this capability is to provide updated Contact information or to refresh it when the Expires interval is exceeded.
PAGE 111
IP-Specific Operations if (gc_ReqModifyCall(crn, parmblkp, EV_ASYNC) < 0) return FAILURE; gc_util_delete_parm_blk(parmblkp); } /* End of function. */ 4.7.8 Implementing Hold and Retrieve via SIP re-INVITE Either party in a SIP dialog (calling or called) can put the call on hold by sending a re-INVITE request that contains a specially configured SDP offer that requests the remote endpoint to suspend RTP streaming.
PAGE 112
IP-Specific Operations GCSET_CHAN_CAPABILITY IPPARM_LOCAL_CAPABILITY • value = IP_CAPABILITY data structure with direction field set to IP_CAP_DIR_LCLRTPRTCPINACTIVE As in the similar case of suspending RTP only, all of the fields in the IP_CAPABILITY structure except for the direction field should be set to the current values for the active media session. The application can start with a copy of the IP_CAPABILITY structure that was retrieved as part of the connection information as described in Section 4.
PAGE 113
IP-Specific Operations the connection information from the original INVITE dialog (see Section 4.6.2, “Getting Media Streaming Status and Connection Information”, on page 155, for details). Alternatively, the application can modify the properties of the streaming session (for example, changing to a different codec) at the same time that it retrieves the call from hold.
PAGE 114
IP-Specific Operations 4.8.2 Supported Q.931 Message IEs Table 5 shows the supported Q.931 message Information Elements (IEs), the parameter set ID and parameter ID that should be included in a GC_PARM_BLK when setting or retrieving the IEs, and the maximum allowed length of the IE value. Table 5. Supported Q.
PAGE 115
IP-Specific Operations Table 6. Supported IEs in Incoming Q.931 Messages Incoming Q.931 Message Note: 4.8.
PAGE 116
IP-Specific Operations 4.9 Setting and Retrieving SIP Message Header Fields The Dialogic® Global Call API supports the setting and retrieving of SIP message header fields in various SIP message types, including INFO, INVITE, NOTIFY, OPTIONS, REFER, and SUBSCRIBE requests.
PAGE 117
IP-Specific Operations Once the GC_PARM_BLK is composed, the application can pass that parm block as a parameter in a Global Call function that directly sends a message (such as gc_Extension( ), which is used to send messages like INFO or OPTIONS, or gc_ReqService( ), which is used to send REGISTER requests) or can preset the header fields for the next message to be sent by calling the gc_SetUserInfo( ) function.
PAGE 118
IP-Specific Operations Table 8.
PAGE 119
IP-Specific Operations Table 8.
PAGE 120
IP-Specific Operations Table 9.
PAGE 121
IP-Specific Operations Table 9. Common Header Fields in Inbound SIP Messages (Continued) SIP header SIP message Global Call event Supported OPTIONS GCEV_EXTENSION if E_SIP_OPTIONS_Access is enabled To ‡ INFO, NOTIFY, SUBSCRIBE GCEV_EXTENSION OPTIONS GCEV_EXTENSION if E_SIP_OPTIONS_Access is enabled REFER GCEV_REQ_XFER if call transfer is enabled (display string and full header also returned in header-specific parameters) † Header field also accessible via field-specific parameter define.
PAGE 122
IP-Specific Operations Table 10 lists the SIP header fields that have field-specific parameter IDs, all of which are deprecated. The table also indicates the size defines that correspond to each parameter ID, each of which is equated to 255. Note that some of these parameters provide access to specific portions of the corresponding header field, such as only the URI or only the display string.
PAGE 123
IP-Specific Operations Table 10.
PAGE 124
IP-Specific Operations application requires the ability to send and receive SIP header fields that are longer than this default maximum length (up to a maximum of 4096 bytes), it can overwrite the default value after initializing the IPCCLIB_START_DATA but before calling gc_Start( ).
PAGE 125
IP-Specific Operations • Content-Disposition † • Content-Encoding † • Content-Language † • Content-Length • CSeq • Date • Diversion † * • Event † * • Expires † * • From † * • Max-Forwards • Min-Expires • Min-SE • Proxy-Authenticate • Proxy-Authorization • RAck • Referred-By † * • Refer-To • Replaces † * • Request-URI † * • Require † • Retry-After • Route • RSeq • Session-Expires • Subscription-State • Supported † • To † * • Unsupported • Via • Warning • WWW-Authenticate † The following code snippet illust
PAGE 126
IP-Specific Operations // all devices are open // register SIP headers to monitor GC_PARM_BLKP parmblkp = NULL; char char char char char char *pAccept = "Accept"; *pAcceptEnc = "Accept-Encoding"; *pAcceptLang = "Accept-Language"; *pAllow = "Allow"; *pRequire = "Require"; *pSupported = "Supported"; gc_util_insert_parm_ref(&parmblkp, IPSET_CONFIG, IPPARM_REGISTER_SIP_HEADER, strlen(pAccept) + 1, pAccept); gc_util_insert_parm_ref(&parmblkp, IPSET_CONFIG, IPPARM_REGISTER_SIP_HEADER, strlen(pAcceptEnc) + 1, p
PAGE 127
IP-Specific Operations 4.9.5 Setting SIP Header Fields for Outbound Messages Note that it is not necessary for applications to register in advance the header field types that it will be setting (as described in Section 4.9.4, “Registering SIP Header Fields to be Retrieved”, on page 180). Registration of header field names is only required when the application needs to retrieve those header fields from received messages.
PAGE 128
IP-Specific Operations string that is the complete header field to be sent, starting with the header field name and including all required syntax elements and punctuation. As permitted in RFC 3261 and other IETF standards, applications can insert multiple header fields of the same type with different values, or can insert a single header field with multiple values in a comma-delimited string.
PAGE 129
IP-Specific Operations #include "gclib.h" .. .. GC_PARM_BLK *pParmBlock = NULL; char *pDestAddrBlk = "1111@127.0.0.1\0"; char *pReqURI = "sip:2222@127.0.0.
PAGE 130
IP-Specific Operations Call utility functions.to retrieve the message type information and individual SIP header fields of interest. Note: The application must retrieve the necessary SIP message header field information by copying the GC_PARM_BLK into its own buffer with gc_util_copy_parm_blk( ) before the next call to gc_GetMetaEvent( ). Once the next gc_GetMetaEvent( ) call is issued, the header information no longer available from the metaevent buffer.
PAGE 131
IP-Specific Operations In addition to the IPPARM_SIP_HDR elements that correspond to the registered header fields, the parm block will also contain elements that use the deprecated field-specific parameter IDs listed in Table 10, “Field-Specific Parameters (Deprecated) for SIP Header Access”, on page 178. Some of these field-specific parameters provide access to a specific part of the corresponding header field (specifically just the display string or just the URI) rather than the complete header field.
PAGE 132
IP-Specific Operations 4.10 Using MIME Bodies in SIP Messages (SIP-T) When using SIP, the Dialogic® Global Call API library supports the sending and receiving of messages that include a single-part or multipart MIME body. This feature was implemented primarily to allow applications to send and receive SIP Telephony (SIP-T) information, which is encoded in a MIME message body as defined in RFC 3372, a document which describes a framework for SIP-PSTN interworking gateways.
PAGE 133
IP-Specific Operations message. If any of the MIME part header fields are longer than 255 bytes (up to the maximum size configured by the application in the max_parm_data_size field in IPCCLIB_START_DATA), the application must use the extended gc_util_insert_parm_ref_ex( ) function rather than the standard gc_util_insert_parm_ref( ) utility function.
PAGE 134
Figure 48. SIP MIME Scenario for Rejected Call App GC GC App gc_MakeCall() with IPSET_MIME INVITE with MIME GCEV_OFFERED with IPSET_MIME gc_SetUserInfo() with IPSET_MIME gc_DropCall() 603 decline with MIME Ack GCEV_TASKFAIL with reason and IPSET_MIME GCEV_DISCONNECTED Figure 49. SIP MIME GC_PARM_BLK Structure n 1 First level GC_PARM_BLK Second level GC_PARM_BLK B1 IPPARM_MIME_PART .....
PAGE 135
4.10.2 Enabling and Configuring the SIP MIME Feature . . INIT_IPCCLIB_START_DATA(&ipcclibstart, 2, ip_virtboard); INIT_IP_VIRTBOARD(&ip_virtboard[0]); INIT_IP_VIRTBOARD(&ip_virtboard[1]); ip_virtboard[0].sip_msginfo_mask = IP_SIP_MSGINFO_ENABLE | IP_SIP_MIME_ENABLE /* override default to enable SIP header and MIME access*/ ip_virtboard[1].sip_msginfo_mask = IP_SIP_MSGINFO_ENABLE | IP_SIP_MIME_ENABLE; /* override default to enable AIP header and MIME access */ . . 4.10.
PAGE 136
INVITE sip:user2@127.0.0.1 SIP/2.0 From: ;tag=0-13c4-3f9fecfb-1a356266-56c9 To: Call-ID: 93d5f4-0-13c4-3f9fecfb-1a356266-2693@127.0.0.1 CSeq: 1 INVITE Via: SIP/2.0/UDP 146.152.84.141:5060;received=127.0.0.1;branch=z9hG4bK-3f9fecfb1a356270-61ce Max-Forwards: 70 Supported: 100rel Mime-Version: 1.0 Contact:
PAGE 137
Table 12.
PAGE 138
IPPARM_MIME_BODY_HEADER [optional parameter] Content-User: Dialogic ;type=demo1 [data from MIME part header in received MIME message] The buffer at the address given in the value of IPPARM_MIME_PART_BODY (0x329823e8 in this example) contains the data that was received in the MIME part body: 01 43 53 0e 00 00 00 95 49 00 10 1e 00 03 0a 1e 00 06 07 1e 03 0d 03 06 02 03 10 26 00 80 27 05 07 90 80 0d 04 a2 88 f5 10 07 03 01 00 03 00 06 33 10 00 10 63 03 89 04 21 63 8b 00 The second, second-level
PAGE 139
Code Example The following code example illustrates the retrieval of MIME information from a GCEV_OFFERED event. It prints out every MIME part header and MIME part body (except for any SDP) that exists in the SIP INVITE message. Note that the example uses the extended utility functions because the parameters for MIME part header fields may be longer than 255 bytes.
PAGE 140
/* Get MIME type info, this has to be the first parameter */ if(IPSET_MIME == ParmDataExt.set_ID && IPPARM_MIME_PART_TYPE == ParmDataExt.parm_ID) { printf("\t Content-Type = %s\n", (char*)ParmDataExt.pData); } else { /* error condition */ printf("\n !!! first parameter in MIME part is not MIME type!!!\n"); return -1; } /* Get the rest of MIME info*/ while (GC_SUCCESS == gc_util_next_parm_ex(parmblkp, &ParmDataExt)) { switch(ParmDataExt.set_ID) { case IPSET_MIME: switch(ParmDataExt.
PAGE 141
} } . . . return 0; } 4.10.4 Sending MIME Information Table 13 lists the Global Call functions that can be used to send SIP messages with MIME information using the IPSET_MIME parameter set ID in the attached GC_PARM_BLK. Except in the cases of and , sending a SIP message with MIME requires two function calls, to set the information, and a second function to cause the library to send the message. Table 13.
PAGE 142
with IPSET_MIME_200OK_TO_BYE and MIME information set with IPSET_MIME are kept independent of each other on a given channel. The data that is to be sent in the MIME part body is copied into the message MIME part from an application buffer. The data in the buffer must match the data type that is specified by the IPPARM_MIME_PART_TYPE parameter.
PAGE 143
2. Insert a required IPPARM_MIME_PART parameter to point to the GC_PARM_BLK structure for the first MIME part in the message using the function. 3. Repeat Step 2 for each additional MIME part, inserting the parameters in order of how the MIME parts should be organized in the message. Set/send message data and clean up After creating and populating the top-level GC_PARM_BLK structure that lists all the MIME parts to be sent in the SIP message, set or send the message and clean up the set-up structures: 1.
PAGE 144
/* Insert Body Size */ gc_util_insert_parm_val(&pParmBlockB, IPSET_MIME, IPPARM_MIME_PART_BODY_SIZE, sizeof(unsigned long), strlen(pBody)); /* Insert MIME part Body Pointer */ gc_util_insert_parm_val(&pParmBlockB, IPSET_MIME, IPPARM_MIME_PART_BODY, sizeof(unsigned long), (unsigned long)pBody); /* Insert other header fields */ gc_util_insert_parm_ref_ex(&pParmBlockB, IPSET_MIME, IPPARM_MIME_PART_HEADER, (unsigned long)(strlen(pPartHeader1) + ), pPartHeader1); /* Insert other header fields */ gc_util_insert_p
PAGE 145
If the MIME memory pool is empty, or if the configured MIME buffer size is smaller than the MIME body of an incoming SIP-T message, a GCEV_TASKFAIL event is sent to the application with the reason set to IPEC_MIME_POOL_EMPTY or IPEC_MIME_BUFF_TOO_SMALL, respectively. In addition, these error conditions also cause a response message with response code 486(Busy Here) to be sent to the remote UA. The current transaction will be terminated without causing the state of the current call to change. 4.
PAGE 146
for user persistence. Second, a default transport protocol setting of TCP or a “;transport=tcp” parameter in the Request-URI header field is not sufficient to force TCP for a BYE request. Instead, it is necessary to also set “;transport=tcp” in the Contact URI header field. Due to network conditions, in certain instances a 1xx Informational Response or an ACK response may be lost and the SIP standards specify that these messages are not re-transmitted.
PAGE 147
When UDP is used as the transport protocol, the SIP stack automatically retries the request on the same address until a timeout occurs or a response is received. When such a timeout occurs there is generally no point in retrying further on the same address, but having the stack automatically retry on any additional addresses that are contained in the DNS server may be useful. All request retry configuration options that enable retry include this type of retry using DNS entries.
PAGE 148
IP_SIP_REQUEST_FAILED Connection failed due to general or unclassified error. IP_SIP_REQUEST_NETWORK_ERROR Connection failed due to network error or local failure. IP_SIP_REQUEST_RETRY_FAILED Failure in request retry logic; retry not attempted. IP_SIP_REQUEST_TIMEOUT Connection failed due to connection timeout. The following code illustrates how an application can extract the failure cause information from the Extension events associated with SIP transport failures.
PAGE 149
default: printf(" Received Unknown Error cause\n"); break; } } 4.13 Sending and Receiving SIP INFO Messages The SIP INFO message (as specified in IETF RFC 2976) provides a means for transporting application-level, session-related control information along the SIP signaling path after the setup of a SIP-controlled session has begun. INFO messages can be sent on an early INVITE-initiated SIP dialog (after a 101-199 provisional response) or on a confirmed dialog.
PAGE 150
in the function call must be GCTGT_GCLIB_CRN, and the t CRN handle for the current call. must be the The following standard header fields are generally required for INFO messages: • To • From • Contact • Request-URI • Diversion • Call-ID If the application does not explicitly set the Request-URI, the library populates it with the URI from the To header field by default.
PAGE 151
The GC_PARM_BLK associated with Extension event will contain a parameter element as follows: ID IPSET_MSG_SIP ID IPPARM_MSGTYPE and one of the following values: • IP_MSGTYPE_SIP_INFO_OK • IP_MSGTYPE_SIP_INFO_FAILED The application can also retrieve the specific SIP response code from the Extension event’s parameter block using the IPSET_MSG_SIP parameter set ID and the parameter ID IPPARM_MSG_SIP_RESPONSE_CODE.
PAGE 152
4.13.3 Receiving an INFO Message When the SIP stack receives an incoming SIP INFO message, it generates a GCEV_CALLINFO event to the application. The application can extract standard message header fields from the parameter block associated with the GCEV_CALLINFO event using the technique described in Section 4.9.6, “Retrieving SIP Message Header Fields”, on page 185.
PAGE 153
4.13.4 Responding to an INFO Message Once an application has received a GCEV_CALLINFO event for a SIP INFO message and extracted the information from the event, it must send a response message.
PAGE 154
gc_util_insert_parm_val(&parmblkp, IPSET_MSG_SIP, IPPARM_MSGTYPE, sizeof(int), IP_MSGTYPE_SIP_INFO_FAILED); // Insert SIP response code gc_util_insert_parm_val(&parmblkp, IPSET_MSG_SIP, IPPARM_MSG_SIP_RESPONSE_CODE, sizeof(int), 501); // transmit INFO response message to network retval = gc_Extension(GCTGT_GCLIB_CRN, crn, IPEXTID_SENDMSG, parmblkp, &retblkp, EV_ASYNC); 4.
PAGE 155
When Global Call automatically responds to an incoming OPTIONS request, there are two possibilities: • If a channel is available to handle the incoming request, Global Call sends a 200 OK message that includes an SDP message body (Content-Type: application/sdp) which indicates the same capabilities that the library would report in an outgoing INVITE request.
PAGE 156
INIT_IPCCLIB_START_DATA(&ipcclibstart, 2, ip_virtboard); INIT_IP_VIRTBOARD(&ip_virtboard[0]); INIT_IP_VIRTBOARD(&ip_virtboard[1]); ip_virtboard[0].sip_msginfo_mask = IP_SIP_MSGINFO_ENABLE | IP_SIP_MIME_ENABLE; ip_virtboard[1].sip_msginfo_mask = IP_SIP_MSGINFO_ENABLE | IP_SIP_MIME_ENABLE; ip_virtboard[0].E_SIP_OPTIONS_Access = ENUM_Enabled; ip_virtboard[1].
PAGE 157
The following parameters IDs are used with the IPSET_SIP_MSGINFO parameter set ID to set the header fields in the OPTIONS message, using the general techniques described in Section 4.9.
PAGE 158
gc_util_insert_parm_ref_ex(&parmblkp, IPSET_SIP_MSGINFO, IPPARM_TO, (unsigned long)(strlen(szTo)+1), szTo); gc_util_insert_parm_ref-ex(&parmblkp, IPSET_SIP_MSGINFO, IPPARM_REQUEST_URI, (unsigned long)(strlen(szRURI)+1), szRURI); gc_util_insert_parm_ref-ex(&parmblkp, IPSET_SIP_MSGINFO, IPPARM_FROM, (unsigned long)(strlen(szFrom)+1), szFrom); gc_util_insert_parm_ref-ex(&parmblkp, IPSET_SIP_MSGINFO, IPPARM_CONTACT_URI, (unsigned long)(strlen(szCntct)+1), szCntct); gc_util_insert_parm_ref_ex(&parmblkp, IPSET_SI
PAGE 159
4.14.4 Receiving Responses to OPTIONS Requests When the Dialogic® Global Call API library’s SIP stack receives a response to a SIP OPTIONS request, it generates a GCEV_EXTENSION event of type IPEXTID_RECEIVEMSG.
PAGE 160
• Contact URI The application must retrieve the necessary SIP message header and body information by copying it into its own buffer before the next call to gc_GetMetaEvent( ). Once the next gc_GetMetaEvent( ) call is issued, the message information is no longer available from the metaevent buffer. The following pseudo-code illustrates how to extract “OK” and “Failed” responses to OPTIONS requests from a GCEV_EXTENSION event.
PAGE 161
4.14.5 Receiving OPTIONS Requests When the Dialogic® Global Call API library is started with the IP_VIRTBOARD.E_SIP_OPTIONS_Access field set to ENUM_Enabled (to allow application access to OPTIONS requests), the library will act in one of two ways when the SIP stack receives a SIP OPTIONS request: • If there is no channel available to handle an incoming connection request (for example, all channels in use or gc_WaitCall( ) not having been called), Global Call automatically sends a “busy” response.
PAGE 162
case GCEV_EXTENSION: if( pextensionBlk->ext_id== IPEXTID_RECEIVEMSG) { while ((l_pParm = gc_util_next_parm(pParmBlock, l_pParm )) != 0) { int l_mtype= (int)(*( l_pParm->value_buf)); switch (l_pParm->set_ID) { case IPSET_MSG_SIP: if(l_pParm ->parm_ID == IPPARM_MSGTYPE) { if(l_mtype== IP_MSGTYPE_SIP_OPTIONS ) { printf("OPTIONS request received\n"); } … } break case IPSET_SIP_MSGINFO: switch(l_pParm ->parm_ID) { case IPPARM_CALLID_HDR: strncpy(g_CurrentCallID,(char*)parmp->value_buf,parmp->value_size); g_Curre
PAGE 163
parm_ID value_buf Default value The Dialogic® Global Call API library ensures that the Allow header field contains all SIP methods supported by the library, which includes the following methods if supplementary services (call transfer) is not enabled: INVITE, CANCEL, ACK, BYE, OPTIONS or the following if supplementary services is enabled: INVITE, CANCEL, ACK, BYE, REFER, NOTIFY, OPTIONS When sending an “OK” response, the IP Call Control library automatically inserts a MIME body part that contains SDP dat
PAGE 164
gc_util_insert_parm_ref_ex(&parmblkp, IPSET_SIP_MSGINFO, IPPARM_SIP_HDR, (unsigned long)(strlen(szAcceptE)+1), szAcceptE); gc_util_insert_parm_ref_ex(&parmblkp, IPSET_SIP_MSGINFO, IPPARM_SIP_HDR, (unsigned long)(strlen(szAcceptL)+1), szAcceptL); gc_util_insert_parm_ref_ex(&parmblkp, IPSET_SIP_MSGINFO, IPPARM_SIP_HDR, (unsigned long)(strlen(szSupp)+1), szSupp); gc_util_insert_parm_ref_ex(&parmblkp, IPSET_SIP_MSGINFO, IPPARM_SIP_HDR, (unsigned long)(strlen(szAllow)+1), szAllow); //insert a message body gc_Ext
PAGE 165
gc_util_insert_parm_val(&parmblkp, IPSET_MSG_SIP, IPPARM_MSG_SIP_RESPONSE_CODE, sizeof(int), 486); gc_Extension(GCTGT_GCLIB_CHAN, boardh, IPEXTID_SENDMSG, parmblkp, &retblkp, EV_ASYNC); The following pseudo-code illustrates sending a “Failed” response with the response code 415, which requires Accept, Accept-Encoding, and Accept-Language header fields.
PAGE 166
4.15 Using SIP SUBSCRIBE and NOTIFY Messages The SIP SUBSCRIBE and NOTIFY methods (as documented in IETF RFC 3265) provide a basic mechanism for event notification between nodes. In the most basic implementation, an entity on a network can use the SUBSCRIBE request to communicate its interest in certain state changes for resources or calls on the network, and those entities (or other entities acting on their behalf) can send NOTIFY messages as notifications when those state changes occur.
PAGE 167
The following code snippet provides an example of enabling message header and body access for two virtual boards: INIT_IPCCLIB_START_DATA(&ipcclibstart, 2, ip_virtboard); INIT_IP_VIRTBOARD(&ip_virtboard[0]); INIT_IP_VIRTBOARD(&ip_virtboard[1]); ip_virtboard[0].sip_msginfo_mask = IP_SIP_MSGINFO_ENABLE | IP_SIP_MIME_ENABLE; ip_virtboard[1].
PAGE 168
The following code snippet illustrates how an application constructs and sends a SUBSCRIBE request.
PAGE 169
// Insert SIP Event field if (pEvent) { gc_util_insert_parm_ref_ex(&parmblkp, IPSET_SIP_MSGINFO, IPPARM_EVENT_HDR, (unsigned long)(strlen(pEvent)), pEvent); } // Insert SIP Call ID field if (pCallID) { gc_util_insert_parm_ref-ex(&parmblkp, IPSET_SIP_MSGINFO, IPPARM_CALLID_HDR, (unsigned long)(strlen(pCallID)), pCallID); } if (parmblkp == NULL) { // memory allocation error return; } // transmit SUBSCRIBE message to network retval = gc_Extension(GCTGT_GCLIB_CHAN, boardh, IPEXTID_SENDMSG, parmblkp, &retblkp, E
PAGE 170
Additionally, the subscriber application may periodically receive an event that indicates the expiration of the subscription duration. Note that the application does not have to respond to an expiration message because the message indicates that the transaction is no longer active.
PAGE 171
/* Handle SIP message information */ case IPSET_SIP_MSGINFO: ProcessSIPMsgInfo(parmp); break; default: break; } } pParmBlock = (GC_PARM_BLK*)(metaeventp->extevtdatap); parmp = NULL; } // determine type of SIP Message and process accordingly int CSubNotMgr::ProcessSIPMsg(GC_PARM_DATA *parmp) { int MessType=0; switch (parmp->parm_ID) { case IPPARM_MSGTYPE: { MessType = (int)(*(parmp->value_buf)); switch (MessType) { case IP_MSGTYPE_SIP_SUBSCRIBE: // process here break; case IP_MSGTYPE_SIP_SUBSCRIBE_ACCEPT: //
PAGE 172
switch (parmp->parm_ID) { case IPPARM_REQUEST_URI: strncpy(requestURI,(char*)parmp->value_buf,parmp->value_size); requestURI[parmp->value_size]='\0'; break; case IPPARM_CONTACT_URI: strncpy(contactURI,(char*)parmp->value_buf,parmp->value_size); contactURI[parmp->value_size]='\0'; break; case IPPARM_DIVERSION_URI: strncpy(diversionURI,(char*)parmp->value_buf,parmp->value_size); diversionURI[parmp->value_size]='\0'; break; case IPPARM_EVENT_HDR: strncpy(event,(char*)parmp->value_buf,parmp->value_size); event[
PAGE 173
A code example that illustrates the general procedure for retrieving information from all incoming messages associated with the SUBSCRIBE and NOTIFY methods is included in Section 4.15.2, “Receiving Responses to SUBSCRIBE Requests”, on page 225. 4.15.4 Responding to SUBSCRIBE Requests Once an application has received a GCEV_EXTENSION event for a SIP SUBSCRIBE request and extracted the information from the event, it must send a response message.
PAGE 174
// Insert SIP Call ID field gc_util_insert_parm_ref_ex(&parmblkp, IPSET_SIP_MSGINFO, IPPARM_CALLID_HDR, (unsigned long)(strlen(m_CurrentCallID)), m_CurrentCallID); if (parmblkp == NULL) { // memory allocation error return; } // transmit NOTIFY message to network retval = gc_Extension(GCTGT_GCLIB_CHAN, boardh, IPEXTID_SENDMSG, parmblkp, &retblkp, EV_ASYNC); if (retval != GC_SUCCESS) { gc_ErrorInfo( &gc_error_info ); printf ("Error : gc_Extension() on HANDLE: 0x%lx, GC ErrorValue: 0x%hx - %s, CCLibID: %i - %s
PAGE 175
// transmit NOTIFY message to network retval = gc_Extension(GCTGT_GCLIB_CHAN, boardh, IPEXTID_SENDMSG, parmblkp, &retblkp, EV_ASYNC); if (retval != GC_SUCCESS) { gc_ErrorInfo( &gc_error_info ); printf ("Error : gc_Extension() on HANDLE: 0x%lx, GC ErrorValue: 0x%hx - %s, CCLibID: %i - %s, CC ErrorValue: 0x%lx - %s\n", boardh, gc_error_info.gcValue, gc_error_info.gcMsg, gc_error_info.ccLibId, gc_error_info.ccLibName, gc_error_info.ccValue, gc_error_info.
PAGE 176
void CSubNotMgr::SendSIPNotify ( char* char* char* char* char* char* pRequestURI, pTo, pFrom, pEvent, pBody, pCallID) { char str[MAX_STRING_SIZE]; char *pBlankBody = " "; sprintf(str, "<--- Sending SIP NOTIFY on device %d\n", hsendboard); printandlog(ALL_DEVICES, MISC, NULL, str, 0); GC_PARM_BLKP GC_PARM_BLKP GC_PARM_BLKP GC_INFO int parmblkp = NULL; // parmblkbody = NULL; // retblkp = NULL; // gc_error_info; // retval = GC_SUCCESS; input parameter block pointer body parms return parameter block GlobalC
PAGE 177
// Insert SIP Event field if (pEvent) { gc_util_insert_parm_ref_ex(&parmblkp, IPSET_SIP_MSGINFO, IPPARM_EVENT_HDR, (unsigned long)(strlen(pEvent)), pEvent); } // Insert SIP CallID field if (pCallID) { gc_util_insert_parm_ref-ex(&parmblkp, IPSET_SIP_MSGINFO, IPPARM_CALLID_HDR, (unsigned long)(strlen(pCallID)), pCallID); } // Insert the message Body if (pBody) { // Insert Content-Type field // Add 1 to strlen for the NULL termination character gc_util_insert_parm_ref_ex(&parmblkbody, IPSET_MIME, IPPARM_MIME_P
PAGE 178
// transmit NOTIFY message to network retval = gc_Extension(GCTGT_GCLIB_CHAN, hsendboard, IPEXTID_SENDMSG, parmblkp, &retblkp, EV_ASYNC); if (retval != GC_SUCCESS) { gc_ErrorInfo( &gc_error_info ); printf ("Error : gc_Extension() on HANDLE: 0x%lx, GC ErrorValue: 0x%hx - %s, CCLibID: %i - %s, CC ErrorValue: 0x%lx - %s\n", boardh, gc_error_info.gcValue, gc_error_info.gcMsg, gc_error_info.ccLibId, gc_error_info.ccLibName, gc_error_info.ccValue, gc_error_info.
PAGE 179
4.15.7 Receiving NOTIFY Requests When the SIP stack receives a SIP NOTIFY request, the Dialogic® Global Call API library generates an Extension event (GCEV_EXTENSION) of type IPEXTID_RECEIVEMSG.
PAGE 180
For an “Accept” response the message sent is a 200 OK, while “Reject” sends a 501 response. In either case, the response message must include the Call-ID header that was received in the NOTIFY request. The following two code snippets illustrate how an application would send “Accept” and “Reject” responses to NOTIFY requests.
PAGE 181
“Reject” Response to NOTIFY Request void CSubNotMgr::SendSIPNotifyReject (void) { char str[MAX_STRING_SIZE]; sprintf(str, "<--- Sending SIP NOTIFY Reject\n"); printandlog(ALL_DEVICES, MISC, NULL, str, 0); GC_PARM_BLKP GC_PARM_BLKP GC_INFO int parmblkp = NULL; // input parameter block pointer retblkp = NULL; // return parameter block gc_error_info; // GlobalCall error information data retval = GC_SUCCESS; gc_util_insert_parm_val(&parmblkp, IPSET_MSG_SIP, IPPARM_MSGTYPE, sizeof(int), IP_MSGTYPE_SIP_NOTIFY_R
PAGE 182
• Generating or Detecting DTMF Tones Using a Voice Resource 4.16.1 Specifying DTMF Support The Dialogic® Global Call API can be used to configure which DTMF transmission modes are supported by the application.
PAGE 183
IP_DTMF_TYPE_INBAND_RTP DTMF digits are sent and received inband via standard RTP transcoding. Inband mode cannot be used when using low bit-rate (LBR) coders. IP_DTMF_TYPE_RFC_2833 DTMF digits are sent and received in the RTP stream as defined in RFC 2833.
PAGE 184
Table 14. Summary of DTMF Mode Settings and Behavior IP_DTMF_TYPE_ RFC_2833 IP_DTMF_TYPE_ ALPHANUMERIC IP_DTMF_TYPE_ INBAND Transmit (Tx) DTMF Mode Receive (Rx) DTMF Mode When using RFC 2833, the payload type is specified using the following parameter element: IPSET_DTMF IPPARM_DTMF_RFC2833_PAYLOAD_TYP and one of the following values: • IP_USE_STANDARD_PAYLOADTYPE – (default payload type (101) • any value in the range 96 to 127 – (dynamic payload type 4.16.
PAGE 185
digits are detected. The events for this notification must be enabled; see Section 4.6.1, “Enabling and Disabling Unsolicited Notification Events”, on page 154. Once the events are enabled, when an incoming DTMF digit is detected, the application receives a GCEV_EXTENSION event, with an extID of IPEXTID_RECEIVE_DTMF. The GCEV_EXTENSION event contains the digit and the method.
PAGE 186
• EV_ASYNC indicates the function operates in asynchronous mode • userattr points to a buffer where user information can be stored Alternatively, the IPT network device and IP Media device can be opened without the voice resource, and the IP line device can be routed to the voice device when needed. Once the voice resource is attached to the IPT network and IPT Media devices, the following voice library functions can be used: • dx_dial( ) to generate DTMF tones • dx_getdig( ) to detect DTMF tones 4.
PAGE 187
4.17.1 Nonstandard UII Message (H.245) To send nonstandard UII messages, use the gc_Extension( ) function in asynchronous mode with an ext_id (extension ID) of IPEXTID_SENDMSG. The target_type should be GCTGT_GCLIB_CRN and the target_id should be the actual CRN. The GC_PARM_BLK must contain parameter elements that identify the message type, the nonstandard data, and the nonstandard data identifier. At the sending end, reception of a GCEV_EXTENSIONCMPLT event indicates that the message has been sent.
PAGE 188
if (rc == -1) { printf("Fail to insert parm"); return -1; } else printf("Sending IP H245 UII Message"); gc_Extension(GCTGT_GCLIB_CRN, crn, IPEXTID_SENDMSG, t_PrmBlkp, &t_RetBlkp, EV_ASYNC); gc_util_delete_parm(t_PrmBlkp); . . . 4.17.2 Nonstandard Facility Message (Q.931) To send a nonstandard Facility message, use the gc_Extension( ) function in asynchronous mode with an ext_id (extension ID) of IPEXTID_SENDMSG. The target_type should be GCTGT_GCLIB_CRN and the target_id should be the actual CRN.
PAGE 189
EXTENSIONEVTBLK structure which in turn contains a GC_PARM_BLK that includes all of the data in the message. See Section 9.2.14, “IPSET_MSG_Q931”, on page 523 and Section 9.2.18, “IPSET_NONSTANDARDDATA”, on page 526 for more information. The following code shows how to set up and send a Q.931 nonstandard facility message.
PAGE 190
The parameter element that identifies the message type is: IPSET_MSG_REGISTRATION IPPARM_MSGTYPE • value = IP_MSGTYPE_REG_NONSTD The parameter element for the Nonstandard Data data is: IPSET_NONSTANDARDDATA IPPARM_NONSTANDARDDATA_DATA • value = Nonstandard Data string, max length = max_parm_data_size (configurable at library start-up) The parameter element for the Nonstandard Data identifier is one (and only one) of the following: IPSET_NONSTANDARDDATA IPPARM_NONSTANDARDDATA_OBJID • value = array of unsigne
PAGE 191
An H.245 UII message can only be sent when a call is in the connected state. A Q.931 nonstandard facility message can be sent in any call state. Figure 50. Sending Protocol Messages Sender Application Receiver GlobalCall GlobalCall Application gc_Extension( ) (ip_ext = IPEXTID_SENDMSG) GCEV_EXTENSIONCMPLT GCEV_EXTENSION (ip_ext = IPEXTID_RECEIVEMSG) 4.18 Using H.
PAGE 192
The Dialogic® Global Call API library supports the ability to send and receive tunneled signaling messages in supported H.225 message types as an optional feature that is disabled by default for backwards compatibility. The ability to send and receive TSMs can only be enabled when starting the system; once enabled, the tunneled signaling message feature cannot be disabled without restarting the system.
PAGE 193
corresponding H.225 message. The duration parameter in the gc_SetUserInfo( ) function must always be GC_SINGLECALL; TSM content cannot persist for more than one H.225 message. The gc_SetUserInfo( ) mechanism cannot be used to preset a tunneled signaling message to be sent in a Setup message because the function call requires a valid CRN, which does not yet exist at that point in the call setup process.
PAGE 194
4.18.3 Composing Tunneled Signaling Messages The process of sending a tunneled signaling message begins by composing a GC_PARM_BLK that contains Global Call parameter elements for the message protocol, the message content, and any nonstandard data. The first parameter element identifies the message protocol.
PAGE 195
The second parameter element for nonstandard data uses one of the following two forms: IPSET_TUNNELEDSIGNALMSG IPPARM_TUNNELEDSIGNALMSG_NSDATA_OBJID • value = nonstandard data object ID string conforming to appropriate ASN.1 format IPSET_TUNNELEDSIGNALMSG IPPARM_TUNNELEDSIGNALMSG_NSDATA_H221NS • value = H.221 nonstandard data protocol information in an IP_H221NONSTANDARD data structure The following code example illustrates the process of composing the parameter block for a tunneled signaling message.
PAGE 196
} else { gc_util_insert_parm_ref(&gcParmBlk, IPSET_TUNNELEDSIGNALMSG, IPPARM_TUNNELEDSIGNALMSG_PROTOCOL_OBJECTID, (unsigned char)sizeof(IP_TUNNELPROTOCOL_OBJECTID), &tsmTpObjId); /* Note the use of the extended gc_util function because TSM data may exceed 255 bytes */ gc_util_insert_parm_ref_ex(&gcParmBlk, IPSET_TUNNELEDSIGNALMSG, IPPARM_TUNNELEDSIGNALMSG_CONTENT, (unsigned char)(strlen(pMsgContent)+1), pMsgContent); /* Now fill in the Tunneled Signaling message Non Standard data fields, if used */ /* Note
PAGE 197
Table 16. H.225 Messages and Global Call Functions for Sending Tunneled Signaling Messages H.225 message to be used to send TSM Mechanism used to set TSM to send Global Call Function used to send H.
PAGE 198
Four of the supported H.
PAGE 199
Table 17. H.225 Messages and Global Call Events for Receiving Tunneled Signaling Messages H.
PAGE 200
message. Applications are then able to extract the data of interest using the gc_util_..._ex( ) functions. The GC_PARM_BLK will always contain the following three parameter elements: IPSET_TUNNELEDSIGNALMSG IPPARM_TSM_CONTENT_EVENT • value = the appropriate TSM_CONTENT_...
PAGE 201
TSM Retrieval Code Example The following code example shows how an application might handle the process of requesting tunneled signaling message after it has received a Global Call event associated with one of the supported H.225 message types.
PAGE 202
{ case IPPARM_TSM_CONTENT_EVENT: printf("\tReceived TSM in message type: %s\n", parm_data_ext.value_buf); break; case IPPARM_TUNNELEDSIGNALMSG_CONTENT: printf("\tReceived extension data (TSM) Msg Content: %s\n", parm_data_ext.value_buf); break; case IPPARM_TUNNELEDSIGNALMSG_PROTOCOLOBJID: printf("\tReceived extension data (TSM) PROTOCOL_OBJID: %s\n", parm_data_ext.value_buf); break; case IPPARM_TUNNELEDSIGNALMSG_ALTERNATEID: printf("\tReceived extension data (TSM) TUNNELPROTOCOL_ALTID: %s\n", parm_data_ext.
PAGE 203
An application has no ability to specify which H.225 message types it wishes to receive UU-IE in, and should therefore be capable of handling UU-IE contained in any of the specified H.225 message types. The maximum data length for the Global Call parameter used for the UU-IE content is configured at system start-up. The maximum data length for this parameter is configured by setting the max_parm_data_size field in the IPCCLIB_START_DATA structure.
PAGE 204
Table 18. H.225 Messages and Global Call Events for Receiving UU-IE H.225 message Global Call event used to notify application Connected GCEV_CONNECTED Release Complete GCEV_DISCONNECTED Facility GCEV_EXTENSION (IPEXTID_RECEIVEMSG) † The GCEV_PROCEEDING event is maskable. 4.19.
PAGE 205
Retrieving UU-IE from Facility Messages Because there is no Global Call state change event associated with a Facility message, a slightly different retrieval mechanism applies to this message type. In the case of a Facility message, the UU-IE is sent to the application in an unsolicited GCEV_EXTENSION event which has an extension ID of IPEXTID_RECEIVEMSG rather than a Global Call state change event.
PAGE 206
default: // Since UUIE data can be present only for the above mentioned events, // return from the fuction for all other events. printf("UUIE retrieval is not supported for this type of event.\n"); return(-1); break; } // Initialize the GC parm data. INIT_GC_PARM_DATA_EXT(&parm); // // // rc if { Now go through all the GC parm datas of the GC parm block to find out if there is a setid/parmid combination of IPSET_CALLINFO/IPPARM_UUIE_ASN1.
PAGE 207
The gc_SetUserInfo( ) function can be used to specify call-related information such as coder information and display information before issuing gc_CallAck( ), gc_AcceptCall( ) or gc_AnswerCall( ). See Section 8.3.26, “gc_SetUserInfo( ) Variances for IP”, on page 487 for more information.
PAGE 208
4.21.1 Alarm Source Object Name In Dialogic® Global Call API, alarms are managed using the Dialogic® Global Call API Alarm Management System (GCAMS). Each alarm source is represented by an Alarm Source Object (ASO) that has an associated name. When using Dialogic® Global Call API with IP, the ASO name is IPM QoS ASO. The ASO name is useful in many contexts, for example, when configuring a device for alarm notification. 4.21.
PAGE 209
if (gc_SetAlarmParm(hMediaDevice, ALARM_SOURCE_ID_NETWORK_ID, ParmSetID_qosthreshold_alarm, &alarm_parm_list, EV_SYNC)!= GC_SUCCESS) { /* handle gc_SetAlarmParm() failure */ printf("SetAlarmParm(hMediaDevice=%d, mode=EV_SYNC) Failed", hMediaDevice); return; } printf("SetAlarmParm(hMediaDevice=%d, mode=EV_SYNC) Succeeded", hMediaDevice); } 4.21.4 Retrieving QoS Threshold Values To retrieve QoS threshold values, use the gc_GetAlarmParm( ) function. See Section 8.3.
PAGE 210
QoS_infop->QoSThresholdData[n].unPercentSuccessThreshold); printf("\tPercent Fail Threshold = %u\n", QoS_infop->QoSThresholdData[n].unPercentFailThreshold); printf("\n\n"); } } 4.21.5 Handling QoS Alarms The application must first be enabled to receive notification of alarms on the specified line device. The following code demonstrates how this is achieved.
PAGE 211
When a GCEV_ALARM event occurs, use the Dialogic® Global Call API Alarm Management System (GCAMS) functions such as, gc_AlarmNumber( ) to retrieve information about the alarm. The following code demonstrates how to process a QoS alarm when it occurs. In this case the application simply logs information about the alarm.
PAGE 212
See the Dialogic® Global Call API Programming Guide for more information about the operation of GCAMS and the Dialogic® Global Call API Library Reference for more information about GCAMS functions. 4.22 Registration In an H.323 network, a Gatekeeper manages the entities in a specific zone and an endpoint must register with the Gatekeeper to become part of that zone.
PAGE 213
• specifying one-time or periodical registration (RAS message: RRQ) • changing registered information (RAS message: RRQ) • removing registered information by value (RAS message: RRQ) • sending non-standard registration message (RAS message: NonStandardMessage) • deregistering (RAS messages: URQ/UCF/URJ) • handling calls according to the gatekeeper policy for directing and routing calls (RAS messages: ARQ/ACF/ARJ, DRQ/DCF/DRJ) Note: For detailed information on RAS negotiation, see ITU-T Recommendation H.
PAGE 214
binding exists between the AOR tom@somewhere.com and the transport address 454554-tom-sdih53@py1.somewhere.com:5063 an INVITE addressed to tom@somewhere.com would be routed by a Proxy to the address 454554-tom-sdih53@py1.somewhere.com:5063. When the application receives the GCEV_OFFERED event for this INVITE, it can extract the “454554-tom-sdih53” portion of the address from the Phone List and use that information to route the call to the appropriate logical SIP endpoint.
PAGE 215
When using SIP, it is important to note that RFC3261 specifies that the “host” portion of a URI that is given as a numeric IPv4 address (for example, 123.211.40.90) and one given as a domain name (for example, example.com) are treated as unique even if they actually resolve to the same entity. Applications should be careful to ensure that the “host” portions of any URIs in all subsequent operations on that binding are consistent with way they were specified during the initial registration. 4.22.
PAGE 216
illustrates how an application might increase the maximum number of registrations on the second of two virtual boards to allow two registrations per user: INIT_IPCCLIB_START_DATA(&ipcclibstart, 2, ip_virtboard); INIT_IP_VIRTBOARD(&ip_virtboard[0]); INIT_IP_VIRTBOARD(&ip_virtboard[1]); ip_virtboard[1].sip_registrar_registrations = 240; /* override defaults no. of registrations*/ Note: 4.22.2.
PAGE 217
H.323 If registration is initiated by a Dialogic® Global Call API application via gc_ReqService( ) and the Gatekeeper rejects the registration, a GCEV_SERVICERESP event containing the result code IPEC_RASReasonInvalidIPEC_RASAddress. If an application’s registration attempt fails for any reason, it is the application’s responsibility to re-register. If the stack receives an unsolicited URQ, it silently responds with a UCF, and immediately tries to re-register with the same Gatekeeper.
PAGE 218
SIP When using SIP, auto-refresh is used by default. If the application does not explicitly set the time_to_live value in the IP_REGISTER_ADDRESS structure (that is, doesn’t change the value from its default value of 0), the call control library automatically sets the Expires header field in the REGISTER request to a a value of 3600 seconds.
PAGE 219
• IP_AUTOREFRESH_ENABLE – enable auto-refresh for a specific registration, using the non-zero value specified in IP_REGISTER_ADDRESS.time_to_live or the default value of 3600 in the Expires header field Note: If this parameter is not present in the GC_PARM_BLK when registration is requested, auto-refresh is enabled by default. 4.22.2.
PAGE 220
The application specifies the Registrar and Alias to query by including the following parameter element in the GC_PARM_BLK that is passed to gc_ReqService( ): IPSET_REG_INFO IPPARM_REG_ADDRESS • value = IP_REGISTER_ADDRESS structure with reg_client and reg_server fields filled in to indicate the desired Registrar address and Alias to query Note: This parameter is optional.
PAGE 221
The overriding or additional information is contained in other elements in the GC_PARM_BLK. The elements that can be included are given in Table 38, “Registration Information When Using H.323”, on page 480 and Table 39, “Registration Information When Using SIP”, on page 482. Note: 4.22.2.8 For SIP, the Sender’s Address of Record that was used to initially register a binding never changes. Any attempt to update this value is ignored.
PAGE 222
If the GC_PARM_BLK contains an IPSET_LOCAL_ALIAS / IPPARM_ADDRESS_TRANSPARENT parameter element with the value "*", all bindings that exist in the specified Registrar for the specified Alias are deleted, regardless of what application created them. 4.22.2.9 Deregistering The Dialogic® Global Call API provides the ability to deregister from a Gatekeeper/Registrar. When deregistering, the application can decide whether to keep the registration information locally or delete it.
PAGE 223
conventional nonstandard messages; see Section 9.2.18, “IPSET_NONSTANDARDDATA”, on page 526. An unsolicited GCEV_EXTENSION event with an extension ID (ext_id) of IPEXTID_RECEIVEMSG can be received that contains a nonstandard registration message.
PAGE 224
4.22.4.1 Registration Example The following code example shows how to populate a GC_PARM_BLK structure that can be used to register an endpoint with a gatekeeper (H.323) or registrar (SIP). The GC_PARM_BLK structure contains the following registration information: • two mandatory parameters required by the generic gc_ReqService( ) function • the protocol type (H.
PAGE 225
/****** Setting address information ***********/ IP_REGISTER_ADDRESS registerAddress; memset(registerAddress, 0, sizeof(IP_REGISTER_ADDRESS)); strcpy(registerAddress.reg_server,"101.102.103.104"); /* set server address*/ if (protocol == IP_PROTOCOL_SIP) { strcpy(registerAddress.reg_client,"user@10.20.30.40"); /* set alias for SIP*/ } registerAddress.max_hops = regMulticastHops; registerAddress.
PAGE 226
int boardUnregisterH323(IN char protocol) { GC_PARM_BLKP pParmBlock = NULL; unsigned long serviceID = 1; int rc,frc; int gc_error; // GC error code int cclibid; // Call Control library ID for gc_ErrorValue long cc_error; // Call Controll library error code char *resultmsg; // String associated with cause code char *lib_name; // Library name for cclibid if (protocol != IP_PROTOCOL_H323 && protocol != IP_PROTOCOL_SIP) { printf("failed bad protocol identifier.
PAGE 227
printf("gc_Start() failed: Unable to retrieve error value\n"); } else { gc_ResultMsg(LIBID_GC, (long) gc_error, &resultmsg); printf("gc_ReqService() failed: gc_error=0x%X: %s\n", gc_error, resultmsg); gc_ResultMsg(cclibid, cc_error, &resultmsg); gc_CCLibIDToName(cclibid, &lib_name); printf("%s library had error 0x%lx - %s\n", lib_name, cc_error, resultmsg); } gc_util_delete_parm_blk(pParmBlock); return GC_ERROR; } printf ("Unregister request to the GK was sent ...
PAGE 228
frc = gc_util_insert_parm_val(&pParmBlock, GCSET_SERVREQ, PARM_ACK, sizeof(unsigned char), 1); if (frc != GC_SUCCESS) { printf("failed in PARM_ACK\n"); termapp(); } frc = gc_util_insert_parm_val(&pParmBlock, IPSET_PROTOCOL, IPPARM_PROTOCOL_BITMASK, sizeof(char), IP_PROTOCOL_H323); /*can be H323, SIP or Both*/ if (frc != GC_SUCCESS) { printf("failed in IPSET_PROTOCOL\n"); termapp(); } rc = gc_ReqService(GCTGT_CCLIB_NETIF, brddev, &serviceID, pParmBlock, NULL, EV_ASYNC); if ( GC_SUCCESS != rc) { printf("gc_Re
PAGE 229
failure is only detected when either the Time To Live interval (programmable, with a default of 20 seconds) or the Response timeout (2 seconds) expires. RAS failure detection times can be improved by setting the Time To Live value in the RAS registration request to a value smaller than the default value, to 10 seconds, for example. When RAS loses the Gatekeeper registration, all existing calls are automatically disconnected by Global Call, and GCEV_DISCONNECTED events are sent to the application.
PAGE 230
standard type of SIP authentication is called “digest authentication”, which refers to the encryption method used for secure transmission of the user’s secret password in the message, and is documented in IETF RFC 2617. To be able to respond automatically respond to authentication challenges, a UAC typically registers one or more triplets containing {realm, username, password}, where realm identifies the protected domain and the username and password identify the specific user.
PAGE 231
appropriate authentication quadruplet was configured in the interim. The reason code for such a termination is IPEC_SIPReasonStatus401Unauthorized or IPEC_SIPReasonStatus407ProxyAuthenticationRequired.
PAGE 232
The elements of the authentication quadruplets are contained in an IP_AUTHENTICATION data structure, with each element having the following characteristics: realm a case-insensitive string that defines the protected domain name. This element must always contain a non-empty string.
PAGE 233
4.24.1 Overview of TLS Internet Protocol security in general and Transport Layer Security in specific are very complex subjects, and a comprehensive discussion is well beyond the scope of this document. But anyone attempting to use TLS must have at least a basic understanding of the concepts and entities involved, and this brief introduction is intended to provide that foundation.
PAGE 234
By using TLS as a connection transport, a SIP entity can send and receive data in a secure authenticated manner. TLS, together with the commonly used Public Key Infrastructure certification distribution mechanism achieves the following goals: • Guarantees the identity of a remote computer • Transmits messages to that remote computer in a secure encrypted manner TLS uses pairs of asymmetrical encryptions keys to guarantee the identity of a remote computer.
PAGE 235
Global Call only supports certificates that use the Privacy Enhanced Mail (PEM) format. Applications will need to convert other formats to PEM format. Similarly, Global Call only supports certificates that use the RSA or DSA key formats. An example of an RSA certificate in PEM format is shown below. Certificate: Data: Version: 1 (0x0) Serial Number: 8 (0x8) Signature Algorithm: md5WithRSAEncryption Issuer: O=RVTEST, L=Metropolis, ST=New York, C=US, CN=udiw@radvision.
PAGE 236
A private key is used to decipher the information encrypted by the public key in the certificate. An example of private key in PEM format is shown below.
PAGE 237
Public Key Algorithm: rsaEncryption RSA Public Key: (1024 bit) Modulus (1024 bit): 00:bc:42:8d:5b:d5:7c:9b:ad:bd:46:3a:63:04:8a: 6a:7b:5e:c3:79:15:cd:4e:83:13:64:ac:3c:dd:ea: 7a:34:51:7f:ce:b1:3b:3d:42:a9:d1:98:9a:88:76: c4:4e:7b:d6:33:db:81:95:4a:01:92:49:5e:f1:bb: 45:47:f9:be:18:f9:af:5d:7b:61:39:78:56:28:31: bd:e8:ef:06:09:44:f8:33:bb:4d:f3:43:fe:7d:18: 88:80:0c:38:fb:be:36:ac:00:1f:74:84:da:fd:3d: d4:48:05:21:aa:e8:db:1c:0d:86:33:ed:c7:bd:55: b8:08:e7:53:7c:ad:67:7f:ed Exponent: 65537 (0x10001) X509v3 e
PAGE 238
0c:1a:f7:e5:bc:00:44:dc:1b:36:17:5c:49:04:a0: a5:6a:d2:99:31:d6:24:a4:76:93:94:69:e2:80:a9: d2:fa:e9:fd:b6:dc:80:17:f2:12:62:1e:46:e8:83: 4a:82:d8:b0:60:a3:6c:5e:60:c0:73:f4:dd:50:db: 9d:16:a0:92:51:67:5d:a5:31 Exponent: 65537 (0x10001) X509v3 extensions: X509v3 Basic Constraints: CA:TRUE Signature Algorithm: sha1WithRSAEncryption 58:f1:e4:37:45:96:e5:fd:9e:96:58:57:79:08:69:35:6f:da: af:16:21:0b:2f:87:d3:37:85:e2:93:6c:0d:fc:7f:25:17:4e: af:93:1a:53:57:69:bb:58:e6:0e:a4:05:ef:a9:3a:16:27:e4: e5:a8:01:54:cb
PAGE 239
X509v3 Basic Constraints: CA:FALSE X509v3 Subject Key Identifier: E6:56:D3:2E:8F:7D:5B:04:99:D6:B0:C9:4C:54:A2:0B:33:31:67:FD X509v3 Authority Key Identifier: DirName:/C=US/ST=New Jersey/O=dialogic.com/CN=hmfurootCA.dialogic.com/emailAddress=h.fu@dialogic.com serial:0B Netscape CA Revocation Url: https://www.sial.org/ca-crl.
PAGE 240
9b:5e:b3:85:92:7c:bb:c8:c9:93:fd:98:fa:e6:54:39:5b:58: 37:1c -----BEGIN X509 CRL----MIIBcDCB2jANBgkqhkiG9w0BAQUFADCBjDEgMB4GA1UEAxMXaG1mdS1zZXJ2ZXJD QS5pbnRlbC5jb20xCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpOZXcgSmVyc2V5MRMw EQYDVQQHEwpQYXJzaXBwYW55MRIwEAYDVQQKEwlpbnRlbC5jb20xHTAbBgkqhkiG 9w0BCQEWDmguZnVAaW50ZWwuY29tFw0wNTExMTYxNjE3MDhaFw0wNTEyMTYxNjE3 MDhaMBwwGgIJAN2GKihEdaaFFw0wNTExMTYxNjE1NDRaMA0GCSqGSIb3DQEBBQUA A4GBAMfeH1wKzK6QRYltNT0srYvLEAaLzklqSmWfyP0Wam5c5NXUe/0/vYgkvV3w mEdAj1CHU1CdjhtCfIfXI5Ytf/T6UG2jiD/kVw
PAGE 241
4.24.2.1 Allocating, Initializing, and Configuring a SIP_TLS_ENGINE Data Structure The process of configuring the TLS feature for a virtual board begins by allocating a SIP_TLS_ENGINE data structure and initializing it to default values using the INIT_SIP_TLS_ENGINE( ) function. After the SIP_TLS_ENGINE structure is initialized, it must be configured for TLS client operation, TLS server operation, or both.
PAGE 242
RSA and DSS certificates. Application cannot use different certificate chains for RSA and DSS certificates at the same time. Each member of the chain_cert_filename array identifies a single certificate in the chain that links the local certificate to the root CA. The order of the chain certificates must start with the intermediate certificate that issues the local certificate.
PAGE 243
Configuring Diffie-Hellman (D-H) Key Exchange Parameters In order to perform a Diffie-Hellman (D-H) key exchange the server must use a D-H group (D-H parameters) and generate a D-H key. As TLS server, Global Call always generates a new D-H key during the negotiation. dh_param_512_filename should points to a PEM-format file that contains D-H parameters with 512-bit key, and dh_param_1024_filename should points to a PEM-format file that contains D-H parameters with 1024-bit key.
PAGE 244
In both cases, the default value set by INIT_SIP_TLS_ENGINE( ) is ENUM_Disabled, which leaves both the UDP and TCP ports open. If the application wishes to block either or both of the ports, it must set the value ENUM_Enabled in the appropriate field or fields. Simple SIP_TLS_ENGINE Configuration Example The following code sample illustrates how an application might set up a simple TLS configuration: #include "gclib.h" .. .. #define BOARDS_NUM 1 .. ..
PAGE 245
/* initialize TLS Engine */ SIP_TLS_ENGINE sip_tls_engine; INIT_SIP_TLS_ENGINE(&sip_tls_engine); /* change default port number */ sip_tls_engine.sip_tls_port = 5062; /* configure local RSA certificate and key */ sip_tls_engine.local_rsa_private_key_filename = "localhost.rsa-key-cert.pem"; sip_tls_engine.local_rsa_private_key_password = "RSAKeyPassword"; sip_tls_engine.local_rsa_cert_filename = "localhost.rsa-key-cert.pem"; /* configure local DSS certificate and key */ sip_tls_engine.
PAGE 246
4.24.2.3 Configuring TCP/TLS Persistence in IP_VIRTBOARD Because TLS operates on top of TCP, the Global Call mechanism for configuring the persistence of TCP connections also affects TLS connections. This configuration is accomplished via the E_SIP_Persistence field in IP_VIRTBOARD as described in Section 4.1.2, “Configuring SIP Transport Protocol”, on page 110 and Section 4.1.2.1, “Configuring TCP Transport”, on page 111.
PAGE 247
4.24.3 Making Calls Using TLS RFC 3261 defines the use of TLS as a transport mechanism by using the “sips:” scheme. When using the “sips:” scheme in a URI (or in any other header that indicates the next hop of a message, such as Route, Via, and others), RFC 3261 mandates the transport to be TLS. This is the reason why TLS will not guarantee a secure delivery end-to-end, but only to the next hop. There are several different scenarios of how a Global Call application can originate a call using TLS.
PAGE 248
Figure 51. Outbound Proxy Configured for TLS Transport with Both IP and Hostname App TLS Client & Server Outbound Proxy (local.com) Global Call Remote UA gc_Start() With TLS client and server configuration, UDP is default transport. Outbound proxy is configured with TLS, both outbound proxy IP and Hostname are configured. gc_MakeCall() destination.address = "sip:friend@remote.com" origination.address = "sip:user@local.
PAGE 249
Figure 52. Outbound Proxy Configured for TLS Transport with Only IP Address Or Hostname App TLS Client & Server Outbound Proxy (local.com) Global Call Remote UA gc_Start() With TLS client and server configuration, UDP is default transport. Outbound proxy is configured with TLS, either outbound proxy IP or Hostname is configured, but not both. gc_MakeCall() destination.address = "sip:friend@remote.com" origination.address = "sip:user@local.com" TLS connection #1 is established INVITE sip:friend@remote.
PAGE 250
2. If the E_SIP_DefaultTransport field in the IP_VIRTBOARD structure is ENUM_TCP, only TCP will be used as transport protocol. No TLS will be used in the initial INVITE. Global Call will always use a “sip:” URI as the local contact URI unless this is specifically changed by the application. The following figure illustrates an initial INVITE with TLS where both source and destination addresses use the “sip:” scheme. In this case, the DNS resolves the required transport to be TLS.
PAGE 251
Source address is “sip:” URI, destination address is “sips:” URI In this scenario, the transport protocol of initial INVITE is TLS and Global Call acts as TLS client. Global Call will always use a “sip:” URI as local contact URI unless the application specifically changes it, which means that the subsequent incoming request message should use UDP because local URI is “sip:”. The following figure illustrates an initial INVITE transaction where TLS is specified via a “sips:” URI as the destination address.
PAGE 252
Source address is “sips:” URI, destination address is “sip:” URI In this scenario, the transport protocol of an initial INVITE is determined using the same process as in the “sip:” source/“sip:” destination case.
PAGE 253
Source address is “sips:” URI, destination address is “sips:” URI In this scenario, the transport protocol of an initial INVITE is TLS and Global Call acts as TLS client and server. Global Call will always use a “sips:” URI as the local contact URI unless the application specifically changes it, which means that the subsequent incoming request message should use TLS because the local URI is “sips:”.
PAGE 254
outbound proxy configuration. Global Call also allows the application to change the contact URI scheme to be different than the initial INVITE by setting the complete contact header as described in Section 4.9.5, “Setting SIP Header Fields for Outbound Messages”, on page 183. For out-of-call request messages, such as REGISTER, OPTIONS, INFO, and SUBSCRIBE/NOTIFY, the transport method depends on the destination address URI scheme as well as the default transport protocol and any outbound proxy configuration.
PAGE 255
4.25.1 Enabling Call Transfer The call transfer supplementary service is a feature that must be enabled at the time the gc_Start( ) function is called. Both H.450.2 and SIP call transfer services are enabled at the same time. If the application tries to use one of the six IP call transfer functions when call transfer was not enabled, the function call fails with an IPERR_SUP_SERV_DISABLED indication. The mandatory INIT_IP_VIRTBOARD( ) function populates the IP_VIRTBOARD structure with default values.
PAGE 256
Figure 57. Global Call Devices for H.450.2 Blind Call Transfer or SIP Unattended Transfer Party A Party B Party C B ldev1 A ldev1 Primary Call B ldev2 C ldev1 Transferred Call To support a successful H.450.2 supervised call transfer or SIP attended call transfer, two Dialogic® Global Call API line devices are eventually utilized at all endpoints.
PAGE 257
. . . case GCEV_OFFERED: { if (metaevent.extevtdatap) { GC_PARM_BLKP parm_blkp = metaevent.
PAGE 258
Figure 59. Call Transfer Glare Condition Precondition: Primary call between A and B is connected (not shown). A (Transfering) App A (Transfering) IP CCLib gc_InvokeXfer(CRNp) B (Transferred) App B (Transferred) IP CCLib C (Transferred To) App C (Transferred To) IP CCLib FACILITY(cInitiate.Invoke) GCEV_REQ_ XFER(CRNp) gc_AcceptXfer(CRNp) GCEV_ACCEPT_ XFER(CRNp) SETUP Event GCEV_OFFERED(LDg/CRNg) is queued up by Global Call, but not processed by the application.
PAGE 259
4.25.5 Call Transfer When Using SIP This section describes specific call transfer procedures when using SIP protocol. For complete SIPspecific call transfer scenarios see Section 3.3, “Call Transfer Scenarios When Using SIP”, on page 74. The topics covered here include: • Enabling GCEV_INVOKE_XFER_ACCEPTED Events • Invoking an Unattended Call Transfer • Invoking an Attended Call Transfer • Processing Asynchronous Call Transfer Events • Handling a Transfer Request • Making a Transferred Call 4.25.5.
PAGE 260
/* Invoke transfer */ memset(&t_gclibmakecallblk, 0, sizeof(GCLIB_MAKECALL_BLK)); strcpy(t_gclibmakecallblk.destination.address, invokeaddr); t_gclibmakecallblk.destination.address_type = GCADDRTYPE_IP; t_gclibmakecallblk.destination.address_plan = GCADDRPLAN_UNKNOWN; t_gcmakecallblk.gclib = &t_gclibmakecallblk; gc_util_insert_parm_ref(&t_pParmBlk, IPSET_CALLINFO, IPPARM_PHONELIST, sizeof(phonelist), phonelist); t_gclibmakecallblk.ext_datap = t_pParmBlk; rc = gc_InvokeXfer(session[channel].
PAGE 261
INT32 processEvtHandler() { METAEVENT metaEvent; GC_PARM_BLK *parmblkp = NULL; : int rc = gc_GetMetaEvent(&metaEvent); if (GC_SUCCESS != rc) { printf("GC_APP : gc_GetMetaEvent() failed\n"); return rc; } long evtType = sr_getevttype(); long evtDev = sr_getevtdev(); int g_extIndex = g_lArray[g_evtdev]; switch (evtType) { /////////////////////////////////////////// // Party A events /////////////////////////////////////////// case GCEV_INVOKE_XFER_ACCEPTED: // remote party has accepted REFER by 2xx response pr
PAGE 262
case GCEV_ACCEPT_XFER_FAIL: // Failed to accept incoming transfer request PrintEventError(&metaEvent); break; case GCEV_REJ_XFER: // Rejected incoming transfer request break; case GCEV_REJ_XFER_FAIL: // Failed to reject incoming transfer request PrintEventError(&metaEvent); break; case GCEV_XFER_CMPLT: // completed transferred call break; case GCEV_XFER_FAIL: // Failed to complete the transferred call PrintEventError(&metaEvent); break; ///////////////////////////////////////// // Party C events ///////////
PAGE 263
int Gc_HandleXferReq(int channel) { if(session[channel].ConfigFileParm.autoRejectCallXfer) { printf("GC_APP : [%d] Reject call xfer request\n",channel); if(GC_SUCCESS != gc_RejectXfer(session[channel].crn, IPEC_SIPReasonStatus502BadGateway, 0, EV_ASYNC)) { printf("GC_APP : [%d] Reject call xfer failed on device 0x%lx\n", channel, session[channel].
PAGE 264
4.26 T.38 Fax Server Dialogic® Global Call API support for T.38 Fax Server is described under the following topics: • T.38 Fax Server Support Overview • Specifying Manual Operating Mode • Initiating a Switch from Audio to T.38 Fax • Associating a T.38 Fax Device with a Media Device When a Fax Request is Received • Accepting/Rejecting a Request to Switch Between Audio and T.38 Fax • Sending a T.38 Fax in a Session Without Audio Established • Receiving a T.
PAGE 265
• For SIP, the association must be made before gc_MakeCall( ) on the outbound call side and gc_AnswerCall( ) on the inbound call side, since media can only be opened after either of these functions. Note: When a Media device is associated with a T.38 Fax device to establish a fax session over an existing audio connection, then when the fax session concludes, the Media device must be disassociated with the T.38 Fax device, optionally reestablishing the audio connection, before the call is dropped.
PAGE 266
4.26.2 Specifying Manual Operating Mode An application must be configured in “Manual” mode to control the association and disassociation of Media and T.38 Fax devices during each call. The mode of operation is set on a board device basis.
PAGE 267
gc_util_insert_parm_ref(&parmblkp, IPSET_FOIP, IPPARM_T38_CONNECT, (sizeof(IP_CONNECT)), (void *)(&ipConnect)); gc_SetUserInfo(GCTGT_GCLIB_CRN, pline->crn, parmblkp, GC_SINGLECALL); gc_util_delete_parm_blk(parmblkp); /* Initiate T.
PAGE 268
INT32 processEvtHandler() { METAEVENT metaEvent; GC_PARM_BLK *parmblkp = NULL; GC_PARM_DATAP t_gcParmDatap = NULL; GC_PARM_BLK *parmblkp2 = NULL; EXTENSIONEVTBLK *ext_evtblkp = NULL; IP_CONNECT ipConnect; : switch (evtType) { case GCEV_EXTENSION: /* received extension event, parse PARM_BLK examine * extension data */ ext_evtblkp = (EXTENSIONEVTBLK *) metaEvent.
PAGE 269
4.26.5 Accepting/Rejecting a Request to Switch Between Audio and T.38 Fax After T.38 coder change request has been received, followed by association of T.38 Fax device with Media device as described in Section 4.26.4, “Associating a T.
PAGE 270
T.38 Fax device with a media device before calling the gc_MakeCall( ) function to actually send the fax information. The association only applies to a single call and can be accomplished by calling the gc_SetUserInfo( ) function on a line device for a single call, or in the GC_MAKECALL_BLK structure when calling gc_MakeCall( ). Note: If using gc_SetUserInfo( ) to make the association on a line device, the duration must be set to GC_SINGLECALL rather than GC_ALLCALLS.
PAGE 271
To answer the T.38 offer, the application must associate a Fax device with the Media device and set local T.38 media capability before calling the gc_AnswerCall( ) function.
PAGE 272
4.26.8 Sending a Request to Switch from T.38 Fax to Audio To request a switch from a T.38 Fax session back to an audio session, the application uses the gc_Extension( ) function, which initiates a RequestMode (H.323) or re-INVITE (SIP) message to actually perform the action. Before initiating the change of coder, the Fax device must be disassociated from the Media device using the gc_SetUserInfo( ) function.
PAGE 273
break; : } : } 4.26.9 Receiving a Request to Switch from T.38 Fax to Audio An application may receive a request to switch from a T.38 Fax session back to an audio session. The request is received as a GCEV_EXTENSION event that is triggered by a RequestMode (H.323) or re-INVITE (SIP) message. Before accepting the incoming request, the application must disassociate the T.38 Fax device from the Media device using the gc_SetUserInfo( ) function, then continue accepting the request as described in Section 4.
PAGE 274
break; : } : } 4.26.10 Terminating a Call After a T.38 Fax Session After a T.38 fax session is finished, and prior to issuing gc_DropCall( ), the T.38 Fax device needs to be disassociated from the Media device using the gc_SetUserInfo( ) function. The following code provides and example.
PAGE 275
Figure 61. Sending G.711 Fax in an Established Audio Session App GC/cclib Remote Device Capable of Signaling, Audio and Fax FAX gc_OpenEx(:N_iptB1T1:M_ipmB1C1) gc_MakeCall() H.323 SETUP with TCS or SIP INVITE to send Origination IP address and RTP port number Call Connected GCEV_CONNECTED fx_open(dxxxB23C1) gc_UnListen() gc_Listen() fx_listen() fx_sndfax() Fax Data via RTP 4.27.2 Receiving G.
PAGE 276
Figure 62. Receiving G.711 Fax in an Established Audio Session App GC/cclib Remote Device Capable of Signaling, Audio and Fax FAX fx_open(dxxxB23C1) gc_OpenEx(:N_iptB1T1:M_ipmB1C1) H.323 SETUPw/TCS or SIP INVITE to send Origination IP address and RTP port number gc_MakeCall() Call Connected GCEV_CONNECTED gc_Unlisten() gc_Listen() fx_listen() fx_recvfax() Fax Data via RTP 4.
PAGE 277
4.29 LAN Disconnection Alarms The Dialogic® Global Call API IP Call Control library allows applications to receive notification of a disruption of traffic over the host network interface. The network disconnection notification uses the standard GCAMS alarm mechanism. The Global Call IP Call Control library provides facilities to notify applications when there is a disruption of a host LAN connection that is handling call control signaling traffic, and when any such disruption is corrected.
PAGE 278
To enable the receipt of signaling LAN disconnect alarm events, the application must perform the following general steps: • Explicitly open the board device. • Register the device handle (from the open operation) with GCAMS using the Global Call function gc_SetAlarmNotifyAll( ). This registration uses the wildcard Alarm Source Object (ASO) ID, ALARM_SOURCE_ID_NETWORK_ID, because the IP Call Control library ASO ID is not known at this point.
PAGE 279
print_alarm_info(&metaevent); { long alarm_number; char *alarm_name; unsigned long alarm_source_objectID; char *alarm_source_object_name; gc_AlarmNumber(metaeventp, &alarm_number); // Will be of type TYPE_LAN_DISCONNECT = 0x01 // or TYPE_LAN_DISCONNECT + 0x10 (LAN connected). gc_AlarmName(metaeventp, &alarm_name); // Will be "Lan Cable Disconnected" or "Lan cable connected". gc_AlarmSourceObjectID(metaeventp, &alarm_source_objectID); // Will usually be = 7.
PAGE 280
The ipm_SetParm( ) function is called asynchronously even though gc_SetUserInfo( ) is a synchronous function. The return value of the ipm_SetParm( ) function call is passed through as the return value for the gc_SetUserInfo( ) call and must be interpreted as it is for the asynchronous ipm_SetParm( ) call; specifically, the success return value only indicates that the ipm_SetParm( ) function began execution successfully.
PAGE 281
IP Call Scenarios 3. 3 This chapter provides common call control scenarios when using Dialogic® Global Call API with IP technology. Topics include: • Basic Call Control Scenarios When Using IP Technology . . . . . . . . . . . . . . . . . . . . . . 51 • Call Transfer Scenarios When Using H.323 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 • Call Transfer Scenarios When Using SIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 • T.
PAGE 282
IP Call Scenarios 3.1.1 Basic Call Setup When Using H.323 or SIP Figure 8 shows the basic call setup sequence when using H.323 or SIP. Notes: 1. This figure assumes that the network and media channels are already open and a media channel with the appropriate media capabilities is attached to the network channel. See Section 8.3.18, “gc_OpenEx( ) Variances for IP”, on page 476 for information on opening and attaching network and media devices and Section 8.3.
PAGE 283
IP Call Scenarios 3.1.2 Basic Call Teardown When Using H.323 or SIP Figure 9 shows the basic call teardown scenario when using Dialogic® Global Call API with H.323 or SIP. Note: Only H.225.0 (Q.931) messages are shown in the sequence below. H.245 messages were omitted in the interest of simplification. Figure 9. Basic Call Teardown When Using H.323 or SIP Application Global Call CC Lib Global Call CC Lib Application Call connected and media streaming established gc_DropCall( ) H.323: Q.
PAGE 284
IP Call Scenarios Note that in some cases it is possible to enable streaming in one direction significantly earlier than in the other direction. To take full advantage of this fact, the Global Call IP call control library initially enables a temporary unidirectional connection, then modifies the connection to be full duplex as soon as that is possible. 3.1.3.1 H.323 FastStart Mode The library’s default for H.
PAGE 285
IP Call Scenarios 3.1.3.2 H.323 SlowStart Mode Many factors affect the opportunities for early media in H.323 SlowStart mode. • Unless both endpoints support what is referred to as “early H.245”, early media is not possible in the H.323 SlowStart connection mode. • When a Global Call application specifies the optional SlowStart mode, or when one endpoint does not support H.
PAGE 286
IP Call Scenarios Figure 12. SIP Early Media, Calling UA Offers SDP Pre condition: Both line devices are IDLE. Called party has executed gc_WaitCall(). "FastStart" is enabled. Calling App If only one Rx coder is specified in offer, streaming is enabled at time of offer. IP CCLib IP CCLib Called App gc_MakeCall( ) INVITE("m=" m , "m="n , ...) Unidirectional media streams are enabled before each respective GCEV_EXTENSION (MEDIAINFO) event is dispatched upon receiving SDP answer.
PAGE 287
IP Call Scenarios 3.2 Call Transfer Scenarios When Using H.323 The Dialogic® Global Call API API functions that support IP call transfer are described in the Dialogic® Global Call API Library Reference. Information on implementing H.450.2 call transfer can be found in Section 4.25, “Call Transfer”, on page 310, and protocol-specific information about the individual call transfer APIs can be found in the subsections of Section 8.3, “Dialogic® Global Call API Function Variances for IP”, on page 444.
PAGE 288
IP Call Scenarios attempt. Note however, that it is not notified as to the end result of the transfer, specifically whether the transfer results in a connection or a no-answer. Instead, the transferring endpoint is only guaranteed notification that the transferred-to endpoint has been alerted to the incoming transferred call offering (that is, ringback). As specified in H.450.2, the ctInitiate.ReturnResult APDU may be returned in either Alerting or Connect.
PAGE 289
IP Call Scenarios 3.2.3 Successful H.450.2 Blind Call Transfer Scenario As indicated in Figure 14, the precondition for blind transfer is that the transferring endpoint (party A) and the transferred endpoint (party B) are participating in an active (primary) call and are in GCST_CONNECTED from the perspective of the Dialogic® Global Call API. Completion of a successful blind transfer results in the eventual termination of the primary call, and the creation of the transferred call.
PAGE 290
IP Call Scenarios Figure 14. Successful H.450.2 Blind Call Transfer Pre condition: Primary call between A and B is connected (not shown). A (Transferring) App A (Transferring) IP CCLib gc_InvokeXfer(CRNp) B (Transferred) App B (Transferred) IP CCLib C (Transferred To) App C (Transferred To) IP CCLib FACILITY(ctInitiate.Invoke) GCEV_REQ_ XFER(CRNp) gc_AcceptXfer(CRNp ) GCEV_ ACCEPT_XFER(CRNp) gc_MakeCall (CRNt, CRNp ) GCEV_DIALING (CRNt) SETUP(ctSetup.
PAGE 291
IP Call Scenarios 3.2.4 Unsuccessful H.450.2 Blind Call Transfer Scenarios There are a several of scenarios where a blind call transfer may fail.
PAGE 292
IP Call Scenarios 3.2.4.2 No Response From Party B As indicated in Figure 16, the transferred endpoint (party B) may not respond to the ctInitiate.ReturnResult APDU which would cause the T3 timer configured as 20 seconds at the transferring endpoint (party A) to expire. As a result, the GCEV_INVOKE_XFER_FAIL termination event would be received at transferring endpoint (party A) and the original primary call is left connected and in the GCST_CONNECTED state from the perspective of both A and B. Figure 16.
PAGE 293
IP Call Scenarios 3.2.4.3 No Response From Party C As indicated in Figure 17, the transferred-to endpoint (party C) may not respond to the incoming call which would cause the T4 timer configured as 20 seconds at the transferred endpoint (party B) to expire. As a result, the transferred endpoint (party B) receives the GCEV_DISCONNECTED event for the transferred call timeout and after sending a ctInitiate.ReturnResult = Unspecified APDU receives the GCEV_XFER_FAIL event on the primary call.
PAGE 294
IP Call Scenarios 3.2.4.4 Party B Clears Primary Call Before Transfer is Completed The primary call may be cleared at any time while a blind transfer is in progress. As indicated in Figure 18, the transferred endpoint (party B) may clear the primary call while awaiting acknowledgement from the transferred-to endpoint (party C). As a result, the GCEV_INVOKE_XFER_FAIL termination event is received at transferring endpoint (party A) followed by a GCEV_DISCONNECTED.
PAGE 295
IP Call Scenarios 3.2.4.5 Party C is Busy When Transfer Attempted The transferred-to endpoint (party C) may also be busy at the time of transfer (unknown to the transferring endpoint). As indicated in Figure 19, this would result in a Release Complete message with Q.931 Cause 17, User Busy, being returned to the transferred endpoint (party B) indicated to its application via a GCEV_DISCONNECTED event with a cause of GCRV_BUSY. The transferred endpoint (party B) returns a ctInitiate.
PAGE 296
IP Call Scenarios 3.2.5 Endpoint Behavior in H.450.2 Supervised Call Transfer This section describes the behavior of each of the three endpoints in a supervised call transfer under H.450.2. The assumed preconditions for supervised call transfer are: • The transferring endpoint (party A) and the transferred endpoint (party B) are participating in an active call, known as the primary call. From the perspective of the Global Call API, party A and party B are both in the GCST_CONNECTED state.
PAGE 297
IP Call Scenarios From this point forward, the behavior in handling the incoming transferred call from the perspective of this endpoint is identical to that of a blind or unsupervised transfer. The only difference is that the secondary, consultation call is disconnected once the transferred call is answered and must be explicitly dropped and released. 3.2.6 Successful H.450.2 Supervised Call Transfer Scenario As indicated in Figure 20, the first precondition for supervised H.450.
PAGE 298
IP Call Scenarios Figure 20. Successful H.450.2 Supervised Call Transfer Pre condition: Primary call between A and B is connected. Secondary (consultation) call between A and C is connected (not shown). A (Transferring) App A (Transferring) IP CCLib gc_InitXfer (CRNs) GCEV_ INIT_XFER (CRNs) gc_InvokeXfer(CRNp, CRNs ) B (Transferred) App B (Transferred) IP CCLib C (Transferred To) App C (Transferred To) IP CCLib Dispatch "dummy" event to synchronize with GC state machine. FACILITY(ctIdentify.
PAGE 299
IP Call Scenarios 3.2.7 Unsuccessful H.450.2 Supervised Transfer Scenarios Note: The same failures that can potentially occur in blind transfer, may take place in supervised transfer as well. See Section 3.2.4, “Unsuccessful H.450.2 Blind Call Transfer Scenarios”, on page 61 for more information. The difference being that the secondary, consultation may optionally be cleared as specified in H.450.2. There are a several other scenarios where a supervised call transfer may fail.
PAGE 300
IP Call Scenarios 3.2.7.1 Party C Timeout As indicated in Figure 21, the user or application at the transferred-to endpoint (party C) may fail to respond to the ctIdentify.Invoke request causing the timer 1 to expire at the transferring endpoint (party A) resulting in an abandoned transfer attempt. As a result, the GCEV_INVOKE_XFER_FAIL termination event is received at transferring endpoint (party A).
PAGE 301
IP Call Scenarios 3.2.7.2 Party C Rejects the Transfer Request As indicated in Figure 22, the user or application at the transferred-to endpoint (party C) may call the gc_RejectInitXfer( ) function to signal via the ctInIdentify.ReturnResult APDU that it cannot participate in a transfer. As a result, the GCEV_INVOKE_XFER_REJ termination event is received at the transferring endpoint (party A).
PAGE 302
IP Call Scenarios 3.2.7.3 Party B Rejects the Transfer Request As indicated in Figure 23, the user or application at the transferred endpoint (party B) may call the gc_RejectXfer( ) function to reject the transfer request and signal via the ctInitiate.ReturnResult APDU that it cannot participate in a transfer. As a result, the GCEV_INVOKE_XFER_REJ termination event is received at transferring endpoint (party A).
PAGE 303
IP Call Scenarios 3.2.7.4 Party B Timeout As indicated in Figure 24, the user or application at the transferred-to endpoint (party C) may receive the transferred call after the T4 timer expires. If this is the case and the callIdentity is cleared as a result of the T4 expiry, the transferred-to endpoint will clear or reject the transferred call as indicated by a GCEV_DISCONNECTED event at the transferred endpoint (party B) and a GCEV_INVOKE_XFER_FAIL event at the transferring endpoint (party A).
PAGE 304
IP Call Scenarios 3.3 Call Transfer Scenarios When Using SIP The Dialogic® Global Call API functions that supports IP call transfer are described in the Global Call API Library Reference; protocol-specific information about the individual call transfer APIs can be found in the subsections of Section 8.3, “Dialogic® Global Call API Function Variances for IP”. General information on implementing call transfer can be found in Section 4.
PAGE 305
IP Call Scenarios In the SIP call transfer protocol the Transferor is notified when the Transferee accepts the REFER transfer request. The Dialogic® Global Call API Library allows this notification to be signaled to the application as a GCEV_INVOKE_XFER_ACCEPTED event. This event is optional, and is disabled (or masked) by default. The party A application can enable and disable this event at any time after the line device is opened using the gc_SetConfigData( ) function. See Section 4.25.5.
PAGE 306
IP Call Scenarios constructed with the local URI—the same as the From or To header, depending on the direction of the initial call INVITE. Optionally, the Transferor can override the default Referred-By header by inserting a Referred-By header in the gc_InvokeXfer( ) parm block. Party A will be notified if REFER is accepted or rejected by transferred endpoint (party B).
PAGE 307
IP Call Scenarios to party A. Sending 202 Accepted to party A starts the REFER subscription, whereupon party B automatically sends a NOTIFY of 100 Trying (with default expiration time of 300 seconds) to party A on CRNp. No further notification of 100 Trying is sent from party B to party A during the call transfer process. Party B retrieves the destination address information from the unsolicited transfer request via the GC_REROUTING_INFO structure passed with the GCEV_REQ_XFER event.
PAGE 308
IP Call Scenarios IP_SIP_MSGINFO_ENABLE in the sip_msginfo_mask field of the IP_VIRTBOARD data structure) when the virtual board was started. 3.3.2.3 Transfer Target or Transferred-To Endpoint (Party C) From the perspective of party C, the transferred call is, for the most part, treated as a typical incoming call. The call is first notified to the application by a GCEV_DETECTED or GCEV_OFFERED event on CRNt.
PAGE 309
IP Call Scenarios 3.3.3.1 Successful Transfer with Notification of Connection Figure 25 illustrates the basic successful scenario, with party A receiving notification from party B after the transferred call between party B and party C has been connected. The SIP dialog for the primary call between party A and party B is automatically disconnected, and both parties then tear down the call using gc_DropCall( ) and gc_ReleaseCallEx( ). Figure 25.
PAGE 310
IP Call Scenarios 3.3.3.2 Successful Transfer with Notification of Ringing Figure 26 illustrates a scenario where party B notifies party A that the transfer has completed as soon as party C responds to the INVITE with a 100 Trying or 180 Ringing. The Call Control Library at Party A disconnects the primary call with party B after the notification and the application then must tear down the call using gc_DropCall( ) and gc_ReleaseCallEx( ). Figure 26.
PAGE 311
IP Call Scenarios 3.3.3.3 Successful Transfer with Early Termination of REFER Subscription Figure 27 illustrates a valid scenario for which Global Call does not support the party B role. In this scenario, party B terminates the REFER subscription with the first NOTIFY, before party A can be notified of the transferred call status.
PAGE 312
IP Call Scenarios Figure 28. Successful SIP Unattended Call Transfer, Party A Clears Primary Call prior to Transfer Completion Precondition: Primary call between A and B is connected (not shown).
PAGE 313
IP Call Scenarios Figure 29. Successful SIP Unattended Call Transfer, Party B Clears Primary Call prior to Transfer Completion Pre condition: Primary call between A and B is connected (not shown).
PAGE 314
IP Call Scenarios 3.3.4 Endpoint Behavior in Attended SIP Transfers The assumed preconditions for attended SIP call transfer (commonly referred to as “supervised call transfer” in other technologies and protocols) are: • The transferring endpoint (party A, or Transferor in SIP terminology) and the transferred endpoint (party B, or Transferee in SIP terms) are participating in an active call, known as the primary call.
PAGE 315
IP Call Scenarios To protect the Transfer Target, the Transferor simply reverses the primary and secondary call CRNs when calling gc_InvokeXfer( ) to reverse the roles of the two remote parties. The original Transfer Target will now send INVITE to the original Transferee, so that the Transferee is effectively “called back” by the Transfer Target.
PAGE 316
IP Call Scenarios 3.3.5 Successful SIP Attended Call Transfer Scenarios This section describes the basic scenario for successful SIP call transfer and the scenarios for recovery from two conditions that can block transfer completion.
PAGE 317
IP Call Scenarios 3.3.5.1 Successful SIP Attended Call Transfer Figure 30 illustrates the basic scenario for successful SIP attended call transfer. The scenario illustrates the use of a gc_InitXfer( ) function call, which is not required in SIP. The GCEV_INIT_XFER completion event in this case contains a dummy rerouting address. Figure 30. Successful SIP Attended Call Transfer Pre condition: Primary call between A and B is connected (not shown).
PAGE 318
IP Call Scenarios 3.3.5.2 Attended Transfer when REFER is Not Globally Supported If protecting or exposing the Transfer Target is not a concern, it is possible to complete an attended transfer when only the Transferor and one other party support REFER. Note that a 405 Method Not Allowed might be returned instead of the 501 Not Implemented response. Figure 31. SIP Attended Call Transfer, Recovery from REFER Unsupported Pre condition: Primary call between A and B is connected (not shown).
PAGE 319
IP Call Scenarios activated such as forking or sequential searching which may result in the triggered INVITE reaching the wrong User Agent. To prevent an incorrect UA answering the INVITE, a Require: replaces header field is included in the Refer-To. This ensures that only the UA which matches the Replaces dialog will answer the INVITE, since any incorrect UA which supports Replaces will reply with a 481 and a UA which does not support Replaces will reply with a 420.
PAGE 320
IP Call Scenarios 3.3.6 Unsuccessful Call Transfer Scenarios All of the scenarios in this section apply to both unattended (blind) transfer and attended (supervised) SIP call transfers. The gc_InitXfer( ) function call and the corresponding GCEV_INIT_XFER termination event are “dummy” operations that are only used to synchronize the Global Call state machine and can safely be ignored in this context. Transfer failures can be caused by any of transfer endpoints as shown in the scenarios.
PAGE 321
IP Call Scenarios Figure 33. SIP Call Transfer Failure - Party B Rejects Call Transfer Pre condition: Primary call between A and B is connected (not shown).
PAGE 322
IP Call Scenarios 3.3.6.3 No Initial NOTIFY after REFER Accepted Figure 35 illustrates a scenario in which the Transferee (party B) does not send a NOTIFY after it accepts the REFER, causing the timer at party A to expire. The original primary call is left connected and in the GCST_CONNECTED state from the perspective of both party A and party B. Figure 35. SIP Call Transfer Failure - No Initial NOTIFY After REFER is Accepted Pre condition: Primary call between A and B is connected (not shown).
PAGE 323
IP Call Scenarios 3.3.6.4 REFER Subscription Expires Figure 36 illustrates a scenario in which the REFER subscription expires, causing both party A and party B to time out. After the timeout, the Transferee application receives a GCEV_XFER_FAIL termination event and the Transferor application receives a GCEV_INVOKE_XFER_FAIL termination event. The original primary call is left connected and in the GCST_CONNECTED state from the perspective of both party A and party B. Figure 36.
PAGE 324
IP Call Scenarios 3.3.6.5 No Response From Party C Figure 37 illustrates a scenario in which the Transfer Target (party C) does not respond to the incoming call from the Transferee (party B) which causes the T4 timer at party B (configured as 20 seconds) to expire. As a result, the Transferee application (party B) receives the GCEV_DISCONNECTED event for the transferred call timeout. The original primary call is left connected and in the GCST_CONNECTED state from the perspective of both A and B.
PAGE 325
IP Call Scenarios 3.3.6.6 Party B Drops Transferred Call Early Figure 38 illustrates a scenario in which the Transferee (party B) drops the transferred call before receiving a response to the INVITE it sent to party C. As a result, the GCEV_INVOKE_XFER_FAIL termination event is received at the Transferor (party A) and the GCEV_XFER_FAIL termination event is received a the Transferee (party B). The original primary call is left connected and in the GCST_CONNECTED state from the perspective of both A and B.
PAGE 326
IP Call Scenarios 3.3.6.7 Party C is Busy When Transfer Attempted Figure 39 illustrates a scenario in which the Transfer Target (party C) is busy at the time the transfer is requested. (This primarily applies to unattended transfers, since the Transferor would be aware that the Transfer Target is busy in an attended transfer.) In this case, the Transferor (party A) receives a GCEV_INVOKE_XFER_FAIL termination event and the Transferee (party B) receives a GCEV_XFER_FAIL termination event.
PAGE 327
IP Call Scenarios 3.4 T.38 Fax Server Call Scenarios Dialogic® Global Call API supports T.38 fax server as described in Section 4.26, “T.38 Fax Server”, on page 320. The following scenarios demonstrate the T.38 fax server capabilities provided when using IP technology (both H.323 and SIP): • Sending T.38 Fax in an Established Audio Session • Receiving T.38 Fax in an Established Audio Session • Sending T.38 Fax Without an Established Audio Session • Receiving T.
PAGE 328
IP Call Scenarios 3.4.1 Sending T.38 Fax in an Established Audio Session In this scenario, the user application uses the Dialogic® Global Call API to open a Media device, configures “Manual” mode of operation and establishes an audio session with the remote device. See Section 4.26.2, “Specifying Manual Operating Mode”, on page 322 for more information on manual mode. A T.38 Fax device is then opened and the application switches from an audio session to a T.38 session.
PAGE 329
IP Call Scenarios 3.4.2 Receiving T.38 Fax in an Established Audio Session In this scenario, the user application uses the Dialogic® Global Call API to open a Media device, configures “Manual” operating mode and establishes an audio session with the remote device. See Section 4.26.2, “Specifying Manual Operating Mode”, on page 322 for more information on manual mode. To prepare to receive fax, the application must also open a T.30 Fax device.
PAGE 330
IP Call Scenarios Figure 41. Receiving T.38 Fax in an Established Audio Session App GC/cclib IPML Remote Device Capable of Signaling, Audio and T.38 FAX Fx_open(dxxxB23C1) gc_SetConfigData(IP_MANUAL_MODE) gc_OpenEx(:N_iptB1T1:M_ipmB1C1) SETUPw/TCS/INVITE to send Origination IP address and RTP Port number gc_MakeCall() Call Connected GCEV_CONNECTED RTP DATA REINVITE/RequestMode to switch to T.38 Fax.
PAGE 331
IP Call Scenarios 3.4.3 Sending T.38 Fax Without an Established Audio Session This scenario describes the sending of T.38 Fax in a media session that does not have audio already established. The application first opens a Media device and a T.38 Fax device and configures “Manual” mode of operation. See Section 4.26.2, “Specifying Manual Operating Mode”, on page 322 for more information on manual mode. The Dialogic® Global Call API is then used to associate the T.
PAGE 332
IP Call Scenarios 3.4.4 Receiving T.38 Fax Without an Established Audio Session This scenario describes the reception of T.38 Fax in a media session that does not have audio already established. The application first opens a Media device and a T.38 Fax device and configures “Manual” operating mode. See Section 4.26.2, “Specifying Manual Operating Mode”, on page 322 for more information on manual mode. When the application receives a T.38 fax request, a GCEV_OFFERED event with T.
PAGE 333
IP Call Scenarios 3.4.5 Sending a Request to Switch From T.38 Fax to Audio In a fax session, when a fax completes, the application can use the Dialogic® Global Call API to issue a request to switch from a T.38 fax session back to an audio session after disassociating the T.38 Fax device from the Media device. When Dialogic® Global Call API notifies the application that the audio session has been reestablished, the application can once again send and receive audio. Figure 44 shows the scenario diagram.
PAGE 334
IP Call Scenarios 3.4.6 Receiving a Request to Switch From T.38 Fax to Audio In a fax session, when a fax completes, the application can receive a request to switch from a T.38 fax session back to an audio session. The application can choose to accept the request after disassociating the T.38 Fax device from the Media device. When Dialogic® Global Call API notifies the application that the audio session has been reestablished, the application can once again send and receive audio.
PAGE 335
IP Call Scenarios 3.4.7 Terminating a Call After a T.38 Fax Session In any scenario where a T.38 session is established and fax is complete, the application can terminate the call without switching to audio. In either outbound or inbound call termination, the application must disassociate the T.38 Fax device from the Media device before calling gc_DropCall( ). This ensures the Media device in the correct state for the next call.
PAGE 336
IP Call Scenarios should follow the scenarios described in Section 3.4.5, “Sending a Request to Switch From T.38 Fax to Audio”, on page 103, Section 3.4.6, “Receiving a Request to Switch From T.38 Fax to Audio”, on page 104, or Section 3.4.7, “Terminating a Call After a T.38 Fax Session”, on page 105.
PAGE 337
Third Party Call Control (3PCC) Operations and Multimedia Support 5. 5 This chapter provides an overview of the libraries and protocols used for third party call control (3PCC) and describes how to use the Dialogic® Global Call API to perform certain third party call control operations in a SIP environment. Topics include: • Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 • Global Call in Third Party Call Control Mode . .
PAGE 338
Third Party Call Control (3PCC) Operations and Multimedia Support The Internet Engineering Task Force (IETF) has defined RFC 3725 - Best Current Practices for Third Party Call Control (3pcc) in the Session Initiation Protocol (SIP). RFC 3725 is available at http://ietf.org/rfc/rfc3725.txt. Section 5.1.
PAGE 339
Third Party Call Control (3PCC) Operations and Multimedia Support SIP uses the Session Description Protocol (SDP) format for negotiating the media parameters of third party call control calls. Further information on SDP is available in the Internet Engineering Task Force (IETF) document RFC 2327 - SDP: Session Description Protocol. RFC 2327 is available at http://ietf.org/rfc/rfc2327.txt. Figure 64 shows a basic call setup sequence for third party call control: Figure 64.
PAGE 340
Third Party Call Control (3PCC) Operations and Multimedia Support 7. The third party call controller then encapsulates the answer (answer1) in an ACK method. This ACK method is then sent to User A (6). User A has now received the ACK message that was required as part of step 3 above. 8. Because the SDP offer (offer1) was generated by User A and the SDP answer (answer1) was generated by User B, the RTP (media stream) flows between User A and User B (7).
PAGE 341
Third Party Call Control (3PCC) Operations and Multimedia Support Note: Per SDP rules (RFC 3264), if an SDP message body does not contain a media level description (at least one m line), the message body must contain connection information (c line must be present). To satisfy this requirement in IPv4 networks, a “black hole” IP address of 0.0.0.0 is provided as part of the c line in the SDP message body.
PAGE 342
Third Party Call Control (3PCC) Operations and Multimedia Support Global Call API library. The host application does not require direct access to the IP Media Library, as shown in Figure 5, “Dialogic® Global Call API Over IP Architecture”, on page 44. When the Dialogic® Global Call API library is initialized in 3PCC mode, the host application is directly responsible for calling the Dialogic® IP Media Library API functions to manage RTP streams. This relationship is shown in Figure 63.
PAGE 343
Third Party Call Control (3PCC) Operations and Multimedia Support When the Dialogic® Global Call API is initialized in 3PCC mode, the call control library (IPCCLIB) does not internally negotiate media session parameters; the host application is responsible for negotiating the following: • coordinating matching audio/video coders • generating SDP data for outgoing SIP messages.
PAGE 344
Third Party Call Control (3PCC) Operations and Multimedia Support CCLIB_START_STRUCT and GC_START_STRUCT structures, contains a media_operational_mode field that determines the Dialogic® Global Call API library mode of operation.
PAGE 345
Third Party Call Control (3PCC) Operations and Multimedia Support • Events • Error Codes • Global Call Functions Invalid in Third Party Call Control Mode 5.2.2.1 IPCCLIB_START_DATA Data Structure The IPCCLIB_START_DATA data structure contains a new media_operational_mode field that determines the Dialogic® Global Call API library mode of operation, first party call control mode (1PCC) or third party call control mode (3PCC). 5.2.2.
PAGE 346
Third Party Call Control (3PCC) Operations and Multimedia Support char sdpMsgFormat[] = "v=0\r\n" "o=Dialogic_IPCCLib %d %d IN IP4 %s\r\n" "s=Dialogic_SIP_CCLIB\r\n" "i=session information\r\n" "c=IN IP4 %s\r\n" "t=0 0\r\n" "m=audio %d 2000 RTP/AVP %d\r\n"; Note: The SDP outbound content is generated by the application. The Dialogic® HMP Software includes an example SDP generator/parser. The example code is described in Section 5.3, “Session Description Protocol Parser/Generator Example”, on page 353.
PAGE 347
Third Party Call Control (3PCC) Operations and Multimedia Support Table 21.
PAGE 348
Third Party Call Control (3PCC) Operations and Multimedia Support Table 22.
PAGE 349
Third Party Call Control (3PCC) Operations and Multimedia Support /* put the SDP content into the parameter block */ rc = gc_util_insert_parm_ref_ex(&gcParmBlk, IPSET_SDP, IPPARM_SDP_OFFER, data_size (void *) sdpMsg); /* set value */ /* parm value */ if (rc != 0) return FAILURE; /* send the re-INVITE message */ if (gc_ReqModifyCall(crn, gcParmBlk, EV_ASYNC) != GC_SUCCESS) return FAILURE; /* cleanup and exit */ gc_util_delete_parm_blk(gcParmBlk); return SUCCESS; } 5.2.2.
PAGE 350
Third Party Call Control (3PCC) Operations and Multimedia Support GC_SINGLECALL and GC_ALLCALLS duration defines imply that the data set is valid for the entire length of the call. Refer to Section 4.3, “Setting Call-Related Information”, on page 121 for an overview of the GC_SINGLECALL and GC_ALLCALLS duration defines. Note: 5.2.2.6 If the host application needs to set a CRN's or a device's parameters with different duration defines, then the application must call gc_SetUserInfo( ) multiple times.
PAGE 351
Third Party Call Control (3PCC) Operations and Multimedia Support Table 24. Global Call Third Party Call Control Mode Error Codes Global Call Error Description EGC_INVALID_IN_1PCC Generated when a 3PCC mode-specific function is called while the Dialogic® Global Call library is initialized in 1PCC mode. EGC_NO_MEDIA_IN_3PCC Generated when a media control function is called while the Dialogic® Global Call library is initialized in 3PCC mode. Section 5.2.2.
PAGE 352
Third Party Call Control (3PCC) Operations and Multimedia Support Table 25. Global Call Functions Invalid in Third Party Call Control Mode (Continued) Global Call Function 5.2.
PAGE 353
Third Party Call Control (3PCC) Operations and Multimedia Support 5.2.6 DTMF Transport The media management interface required to support in-band DTMF transport is not available when the Dialogic® Global Call API is initialized in 3PCC mode. As a result, the application must use IP Medai Library functions to specify the type of DTMF transport to use (in-band or out-ofband). 5.2.7 T.
PAGE 354
Third Party Call Control (3PCC) Operations and Multimedia Support • Cancelling a re-INVITE Request • Receiving an Invalid Answer SDP • OPTIONS Request on an Active Dialog 5.4.1 First Party Call Establishment in Third Party Call Control Mode Figure 67 shows how to implement a simple point-to-point SIP call between two endpoints (party A and party B). The Dialogic® Global Call API library is initialized in 3PCC mode. A third party call controller is not used: Figure 67.
PAGE 355
Third Party Call Control (3PCC) Operations and Multimedia Support 5.4.2 Basic Third Party Call Control Establishment Figure 68 and Figure 69 show how to establish a basic third party call control call. A third party call controller, party B, establishes signaling connections to two different endpoints, party A and party C.
PAGE 356
Black Hole SDP contains m line IP address 0.0.0.
PAGE 357
IPMEV_MODIFY _MEDIA Global Call Library A (IPCCLIB) Dialogic® Global Call IP Technology Guide — November 2007 Dialogic Corporation GCEV_SIP_ACK no SDP GCEV_ACCEPT _MODIFY_CALL gc_AcceptModifyCall SDP Answer 2 GCEV_REQ MODIFY_CALL SDP Offer 2 Application A ipm_ModifyMedia (TxRx) IPML Library A RTP GCEV_SIP_ACK_OK ACK No SDP RTP GCEV_SIP_ACK gc_SipAck IPMEV_MODIFY _MEDIA ipm_ModifyMedia (TxRx) Application C GCEV_ANSWERED SDP Answer 2 Global Call Library C (IPCCLIB) GCEV_SIP_ACK_OK gc_SipA
PAGE 358
Third Party Call Control (3PCC) Operations and Multimedia Support 5.4.3 Alternate Third Party Call Control Establishment Figure 70, Figure 71, and Figure 72 show an alternate third party call control flow. In this sequence, party A, establishes a dialog and media connection with another user agent, party B. Party B then establishes a dialog with a third user agent, party C.
PAGE 359
Dialogic® Global Call IP Technology Guide — November 2007 Dialogic Corporation IPMEV_MODIFY _MEDIA Global Call Library A (IPCCLIB) GCEV_SIP_ACK_OK gc_SipAck GCEV_SIP_200OK GCEV_CONNECTED GCEV_ALERTING SDP Answer 1 GCEV_DIALING gc_MakeCall SDP Offer 1 Application A ipm_ModifyMedia (TxRx) IPML Library A GCEV_ACCEPT gc_AcceptCall gc_AnswerCall GCEV_SIP_ACK GCEV_ANSWERED Global Call Library C (IPCCLIB) SDP added by the application in a provisional response will be automatically included in the
PAGE 360
IPMEV_MODIFY _MEDIA GCEV_REQ _MODIFY_CALL SDP Offer 2 Global Call Library A (IPCCLIB) gc_AcceptModifyCall SDP Answer 2 Destination IP address changed.
PAGE 361
IPML Library A Global Call Library A (IPCCLIB) Dialogic® Global Call IP Technology Guide — November 2007 Dialogic Corporation GCEV_SIP_ACK GCEV_ACCEPT _MODIFY_CALL Application A Global Call Library B (IPCCLIB) GCEV_SIP_ACK_OK ACK gc_SipAck GCEV_SIP_ACK_OK gc_SipAck SDP Answer 2 IPMEV_STOP ipm_Stop GCEV_SIP_200OK Application B RTP ACK SDP Answer 2 IPML Library B GCEV_SIP_ACK IPML Library C IPMEV_MODIFY _MEDIA ipm_ModifyMedia (Tx/Rx) Application C GCEV_ANSWERED SDP Answer 2 Global Call
PAGE 362
Third Party Call Control (3PCC) Operations and Multimedia Support 5.4.4 Modifying the Coder When running in 3PCC mode, the host application can use the re-INVITE functionality to modify the coders of an active dialog. This section provides the following message sequence diagrams: • Successfully Modifying the Coder • Unsuccessfully Modifying the Coder 5.4.4.
PAGE 363
Third Party Call Control (3PCC) Operations and Multimedia Support Figure 73. Successfully Modifying the Coder (part one) IPML Library A Application A Global Call Library A (IPCCLIB) Global Call Library B (IPCCLIB) Application B gc_MakeCall SDP Offer 1 SDP offer has only one receive coder specified, allowing IPML to "start early" on the offering side.
PAGE 364
Third Party Call Control (3PCC) Operations and Multimedia Support Figure 74.
PAGE 365
Third Party Call Control (3PCC) Operations and Multimedia Support 5.4.4.2 Unsuccessfully Modifying the Coder Figure 75 shows a message sequence diagram for an unsuccessful attempt at modifying the coder of an active dialog: Figure 75.
PAGE 366
Third Party Call Control (3PCC) Operations and Multimedia Support 5.4.5 Cancelling a re-INVITE Request Figure 76 shows the host application behavior when a re-INVITE request has been cancelled. The re-INVITE request is initially made to modify the coder used by the active dialog: Figure 76.
PAGE 367
Third Party Call Control (3PCC) Operations and Multimedia Support 5.4.6 Receiving an Invalid Answer SDP Figure 77 depicts host application behavior when an invalid answer SDP is received.
PAGE 368
Third Party Call Control (3PCC) Operations and Multimedia Support Figure 77. Receiving an Invalid Answer SDP IPML Library A Global Call Library A (IPCCLIB) Application A Global Call Library B (IPCCLIB) Application B gc_MakeCall SDP Offer 1 GCEV_DIALING ipm_StartMedia (RCV_ONLY) INVITE SDP Offer 1 GCEV_OFFERED SDP Offer 1 IPMEV_START_MEDIA IPML Library B SDP offer has only one receive coder specified, allowing IPML to "start early" on the originating side.
PAGE 369
Third Party Call Control (3PCC) Operations and Multimedia Support 5.4.7.1 OPTIONS Request Without a MIME Body When performing SIP OPTIONS transactions in 3PCC mode, SDP content is always delivered in a parameter block attached to the Global Call event as an IPSET_SDP / IPPARAM_OPTION_ANSWER or IPSET_SDP / IPPARM_OPTION_OFFER parameter element regardless of MIME body inclusion.
PAGE 370
Third Party Call Control (3PCC) Operations and Multimedia Support Figure 78.
PAGE 371
Third Party Call Control (3PCC) Operations and Multimedia Support Figure 79.
PAGE 372
Third Party Call Control (3PCC) Operations and Multimedia Support 5.5.2 Requesting an I-Frame in SIP SIP provides a way to request the transmission of an Intraframe as defined by the “expired” IETF draft draft-levin-mmusic-xml-schema-media-control-03. The draft specification defines an XML schema (shown below) that is attached as a MIME body to a SIP INFO message:
PAGE 373
Third Party Call Control (3PCC) Operations and Multimedia Support // insert the body if (gc_util_insert_parm_val(&gcParmBlk_mime, IPSET_MIME, IPPARM_MIME_PART_BODY, sizeof(unsigned long), (unsigned long)(c_iFrameRequest)) < 0) { agwReport(ERROR_GCALL, s_eType, "SendIFrameRequest() -> gc_util_insert_parm_val() failed on %s for IPPARM_MIME_PART_BODY ", m_devName); bOk = false; } // insert the list of parmBlks into the top level parmBlk if (gc_util_insert_parm_val(&gcParmBlk_mime1, IPSET_MIME, IPPARM_MIME_PAR
PAGE 374
Third Party Call Control (3PCC) Operations and Multimedia Support 374 Dialogic® Global Call IP Technology Guide — November 2007 Dialogic Corporation
PAGE 375
Building Dialogic® Global Call API IP Applications 6. 6 This chapter describes the IP-specific header files and libraries required when building applications. • Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 • Required Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 • Required System Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 376
Building Dialogic® Global Call API IP Applications 6.3 Required System Software The Dialogic® Host Media Processing (HMP) Software must be installed on the development system. See the Dialogic® Software Installation Guide for your Dialogic® HMP Software release for further information.
PAGE 377
Debugging Dialogic® Global Call API IP Applications 7. 7 This chapter provides information about debugging Dialogic® Global Call API IP applications: • Debugging Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 • Configuring the Logging Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 7.
PAGE 378
Debugging Dialogic® Global Call API IP Applications client An entity for identifying a device, component, or function that is to be traced by the RTF. The RTF modules for the IP Call Control library include a large number of client entities to provide a high degree of control over what statements are written to the log file; these clients are listed in the following sections which describe how to configure the logging facility.
PAGE 379
Debugging Dialogic® Global Call API IP Applications Module Sections The RtfConfig.xml file contains a number of module sections, each of which controls the logging of trace statements for a specific RTF module. Three RTF modules apply to the IP Call Control library: gc_h3r, h323_stack, and sip_stack. Each module section begins with a tag (with name and state attributes) and ends with a tag.
PAGE 380
Debugging Dialogic® Global Call API IP Applications In the gc_h3r module, the “MLabel” statement for the Warning label enables or disables the logging of all statements from the gc_h3r module that have LEVEL_WARNING in them regardless of the state settings of the “MClient” elements. The “MLabel” statement for the Debug label, on the other hand, interacts with the state settings of the “MClient” elements.
PAGE 381
Debugging Dialogic® Global Call API IP Applications SH_UNPACK (formerly M_SH_UNPACK) Sharon Unpacker SH_BOARD (formerly M_BOARD) Sharon Board Device. SH_MONITOR (formerly M-MON) Sharon Manager (host LAN monitor) H323_SIG_MGR (formerly M_SIG_MAN) H.323 Signal Adaptation Layer (Sigal) Manager H323_CALL_MGR (formerly M_CALL_MAN) H.323 Call Manager H323_SIGNAL (formerly M_SIGNAL) H.323 Signaling H323_CONTROL (formerly M_CONTROL) H.323 Control H323_CH_MGR (formerly M_CHAN_MAN) H.
PAGE 382
Debugging Dialogic® Global Call API IP Applications SIP_CAPS (formerly M_SIP_CAP) SIP Capabilities SIP_SIG_DEC (formerly M_SIP_DEC) SIP Signal Adaptation Layer Decoder SIP_SIG_ENC (formerly M_SIP_ENC) SIP Signal Adaptation Layer Encoder SIP_IPC (formerly M_SIP_IPC) Inter-Process Communication SIP_INFO (formerly M_INFO) SIP Information SIP_REFER (formerly M_REFER) SIP Refer SIP_PRACK (formerly M_PRACK) SIP Protocol Acknowledgement SIP_AUTHENT (formerly M_AUTHENT) SIP Authenticator SIP_SUBSYS (formerly M_S_S
PAGE 383
Debugging Dialogic® Global Call API IP Applications The Error label is normally enabled globally. The Debug label is enabled and disabled on the module level, and if the label is enabled the logging of these statements is controllable on an individual client basis. The state of the Warning label has no effect on the sip_stack module. The sip_stack module in the RtfConfig.
PAGE 384
Debugging Dialogic® Global Call API IP Applications The h323_stack module in the RtfConfig.xml file begins with the statement: Following this statement is an “MLabel” statement to set the local state of the Debug label, which is disabled (state="0") in the default RtfConfig.
PAGE 385
Debugging Dialogic® Global Call API IP Applications • PER † • PERERR † • Q931† • Q931ERR • LI • TIMER • ANNEXE • SSEERR • SSEAPI • SSEAPICB • SUPS • SSCHAN Dialogic® Global Call IP Technology Guide — November 2007 Dialogic Corporation 385
PAGE 386
Debugging Dialogic® Global Call API IP Applications 386 Dialogic® Global Call IP Technology Guide — November 2007 Dialogic Corporation
PAGE 387
IP-Specific Function Information 8. 8 Certain Dialogic® Global Call API functions have additional functionality or perform differently when used with IP technology. The generic function descriptions in the Dialogic® Global Call API Library Reference do not contain detailed information for any specific technology. Detailed information in terms of the additional functionality or the difference in performance of those functions when used with IP technology is contained in this chapter.
PAGE 388
IP-Specific Function Information gc_AlarmNumber( ) Supported gc_AlarmNumberToName( ) Supported gc_AlarmSourceObjectID( ) Supported gc_AlarmSourceObjectIDToName( ) Supported gc_AlarmSourceObjectName( ) Supported gc_AlarmSourceObjectNameToID( ) Supported gc_AnswerCall( ) Supported in asynchronous mode only, with variances described in Section 8.3.
PAGE 389
IP-Specific Function Information gc_CompleteTransfer( ) Not supported gc_CRN2LineDev( ) Supported gc_Detach( ) Supported in asynchronous mode only in 1PCC operating mode; not supported in 3PCC operating mode gc_DropCall( ) Supported in asynchronous mode only, with variances described in Section 8.3.7, “gc_DropCall( ) Variances for IP”, on page 448 gc_ErrorInfo( ) Supported gc_ErrorValue( ) Supported, but deprecated. Use gc_ErrorInfo( ).
PAGE 390
IP-Specific Function Information gc_GetCRN( ) Supported gc_GetCTInfo( ) Supported with variances described in Section 8.3.
PAGE 391
IP-Specific Function Information gc_HoldAck( ) Not supported gc_HoldCall( ) Not supported gc_HoldRej( ) Not supported gc_InitXfer( ) Supported with variances described in Section 8.3.14, “gc_InitXfer( ) Variances for IP”, on page 455 gc_InvokeXfer( ) Supported with variances described in Section 8.3.15, “gc_InvokeXfer( ) Variances for IP”, on page 456 gc_LinedevToCCLIBID( ) Supported gc_Listen( ) Supported with variances described in Section 8.3.
PAGE 392
IP-Specific Function Information gc_ReqANI( ) Not supported gc_ReqModifyCall( ) IP-specific function. See page 414 for full details. gc_ReqMoreInfo( ) Not supported gc_ReqService( ) Supported in asynchronous mode only, with variances described in Section 8.3.22, “gc_ReqService( ) Variances for IP”, on page 479 gc_ResetLineDev( ) Supported in asynchronous mode only gc_RespService( ) Supported in asynchronous mode only, with variances described in Section 8.3.
PAGE 393
IP-Specific Function Information gc_SetCallingNum( ) Not supported gc_SetCallProgressParm( ) Not supported gc_SetChanState( ) Not supported gc_SetConfigData( ) Supported in asynchronous mode only, with variances described in Section 8.3.25, “gc_SetConfigData( ) Variances for IP”, on page 484 gc_SetEvtMask( ) Not supported gc_SetInfoElem( ) Not supported gc_SetParm( ) Not supported gc_SetupTransfer( ) Not supported gc_SetUserInfo( ) Supported with variances described in Section 8.3.
PAGE 394
IP-Specific Function Information gc_SwapHold( ) Not supported gc_TransmitAlarms( ) Not supported gc_UnListen( ) Supported with variances described in Section 8.3.
PAGE 395
IP-Specific Function Information • gc_util_next_parm_ex( ) • INIT_GC_PARM_DATA_EXT( ) • INIT_IP_VIRTBOARD( ) • INIT_IPCCLIB_START_DATA( ) Note: The new gc_util_..._ex( ) functions are backwards compatible with existing gc_util_...( ) functions and may be used with any Dialogic® Global Call API technology, but IP call control is currently the only technology where these functions must be used to support parameter data longer than 255 bytes. The same information on the gc_util_...
PAGE 396
gc_AcceptModifyCall( ) — accept proposed modification of call characteristics gc_AcceptModifyCall( ) accept proposed modification of call characteristics Name: int gc_AcceptModifyCall (crn, parmblkp, mode) Inputs: CRN crn • call reference number of call targeted for modification GC_PARM_BLK *parmblkp • pointer to GC_PARM_BLK which contains attributes of call which are being accepted (optional in 1PCC mode) unsigned long mode • completion mode (EV_ASYNC) Returns: 0 if successful <0 if unsuccessful Inc
PAGE 397
accept proposed modification of call characteristics — gc_AcceptModifyCall( ) The function returns either <0 (to indicate failure) or 0 depending only upon the validity of the parameters. The function return does not indicate any status as to the success or failure of the sending of the response message. The final result of the attempt to send the response is provided in termination events.
PAGE 398
gc_AcceptModifyCall( ) — accept proposed modification of call characteristics request. In this case, the library sends a 488 Not Acceptable Here response to the remote party to terminate the re-INVITE, and generates a GCEV_REJECT_MODIFY_CALL event to notify the application.
PAGE 399
accept proposed modification of call characteristics — gc_AcceptModifyCall( ) gc_SetConfigData( ) function. If this parameter value has not been set, the function call will fail with an error value of IPERR_BAD_PARM. • Only one modification transaction can be pending in a call at any given time. Until the pending re-INVITE has been accepted, rejected, or canceled, no additional re-INVITE can be sent by either party. • Only one attempt to send a response to a re-INVITE request can be pending at a time.
PAGE 400
gc_AcceptModifyCall( ) — accept proposed modification of call characteristics void process_event(void) { METAEVENT metaevent; GC_INFO t_info; /* Populate the metaEvent structure */ if(GC_SUCCESS != gc_GetMetaEvent(&metaevent)) /* process GlobalCall events */ if ((metaevent.flags & GCME_GC_EVENT) == 0) return; return; switch (metaevent.evttype) { . . . case GCEV_REQ_MODIFY_CALL: /* request to modify call attribute */ { GC_PARM_BLKP parm_blkp = (GC_PARM_BLKP) metaEvent.
PAGE 401
accept proposed modification of call characteristics — gc_AcceptModifyCall( ) else /* not acceptable so respond with SIP Client Error */ /* final response of 488 Not Acceptable Here */ if (gc_RejectModifyCall(crn, IPEC_SIPReasonStatus488NotAcceptableHere, EV_ASYNC) < 0) /* failure logic here */ break; } case GCEV_ACCEPT_MODIFY_CALL: . . . /* notify user of changed attribute */ . . .
PAGE 402
gc_AcceptModifyCall( ) — accept proposed modification of call characteristics // Assume application has enabled GCEV_200OK and GCEV_SIP_ACK eventing. . . . /* Dialogic Header Files */ #include #include . . . /* SRL event handler: */ for (;;) { if (-1 != sr_waitevt(500)) process_event(); } void process_event(void) { METAEVENT metaevent; GC_INFO t_info; /* Populate the metaEvent structure */ if(GC_SUCCESS != gc_GetMetaEvent(&metaevent)) /* process GlobalCall events */ if ((metaevent.
PAGE 403
accept proposed modification of call characteristics — gc_AcceptModifyCall( ) frc = gc_util_insert_parm_ref_ex(replyParmblkp, IPSET_SDP, IPPARM_SDP_ANSWER, sdpResponse, sdpResponseSize); if (frc != GC_SUCCESS) { // call application error handler to drop the call and log the error. applicationHandleError(...); break; } proposal_accepted = true; } } else { // No SDP was present in re-Invite. This is a re-Invite delayed offer.
PAGE 404
gc_AcceptModifyCall( ) — accept proposed modification of call characteristics /* can optionally call gc_RejectModifyCall( ) to retry */ . . . break; case GCEV_REJECT_MODIFY_CALL: . . . /* notify user of rejected attribute */ . . . break; case GCEV_REJECT_MODIFY_CALL_FAIL: /* process failure to reject request */ if (gc_ResultInfo(&metaevent, &t_info) < 0) { /* failure logic here */ } /* process information contained in t_info */ /* can optionally call gc_RejectModifyCall( ) to retry */ . . .
PAGE 405
accept proposed modification of call characteristics — gc_AcceptModifyCall( ) case GCEV_SIP_ACK: // Unsolicited event indicating SIP ACK was received on an invite/re-invite request. // This metaevent will contain an IPSET_SDP/IPPARM_SDP_ANSWER in an inbound // invite/re-invite delayed offer call scenario. . . . break; . . .
PAGE 406
gc_RejectModifyCall( ) — reject proposed modification of call attributes gc_RejectModifyCall( ) reject proposed modification of call attributes Name: int gc_RejectModifyCall (crn, reason, mode) Inputs: CRN crn • call reference number of call targeted for modification unsigned long reason • reason for rejecting request to change call attribute unsigned long mode • completion mode (EV_ASYNC) Returns: 0 if successful <0 if unsuccessful Includes: gclib.
PAGE 407
reject proposed modification of call attributes — gc_RejectModifyCall( ) attribute modifications are not performed and the call state remains as it was prior to receiving the incoming re-INVITE request. GCEV_REJECT_MODIFY_CALL_FAIL Unsuccessful termination event. Indicates that the signaling of the rejection response failed. The re-INVITE transaction is still in progress and the application may make another attempt to respond via a new call to gc_AcceptModifyCall( ) or gc_RejectModifyCall( ).
PAGE 408
gc_RejectModifyCall( ) — reject proposed modification of call attributes . . . /* Dialogic Header Files */ #include #include . . . /* SRL event handler: */ for (;;) { if (-1 != sr_waitevt(500)) } process_event(); void process_event(void) { METAEVENT metaevent; GC_INFO t_info; /* Populate the metaEvent structure */ if(GC_SUCCESS != gc_GetMetaEvent(&metaevent)) return; /* process GlobalCall events */ if ((metaevent.flags & GCME_GC_EVENT) == 0) return; switch (metaevent.evttype) { . . .
PAGE 409
reject proposed modification of call attributes — gc_RejectModifyCall( ) updateRTPGUI(&rtp); proposal_accepted = TRUE; } } } /* /* /* if { if proposal is acceptable accept the request */ format accepted attributes (i.e.
PAGE 410
gc_RejectModifyCall( ) — reject proposed modification of call attributes . . . } /* endof switch */ } /* endof process_event function */ The following code example illustrates how the gc_RejectModifyCall( ) function is used in third party call control (3PCC) operating mode. // Assume application has enabled GCEV_200OK and GCEV_SIP_ACK eventing. . . . /* Dialogic Header Files */ #include #include . . .
PAGE 411
reject proposed modification of call attributes — gc_RejectModifyCall( ) // // // // if applicationModifyMedia is a user supplied function that analyzes the raw SDP; it starts the media and provides a raw sdp answer for the remote endpoint if the media offer is acceptable. This function is not supplied in this sample. (applicationModifyMedia(parm.pData, parm.
PAGE 412
gc_RejectModifyCall( ) — reject proposed modification of call attributes case GCEV_ACCEPT_MODIFY_CALL_FAIL: /* process failure to change attribute */ if (gc_ResultInfo(&metaevent, &t_info) < 0) { /* failure logic here */ } /* process information contained in t_info */ /* can optionally call gc_RejectModifyCall( ) to retry */ . . . break; case GCEV_REJECT_MODIFY_CALL: . . . /* notify user of rejected attribute */ . . .
PAGE 413
reject proposed modification of call attributes — gc_RejectModifyCall( ) case GCEV_SIP_ACK: // unsolicited event indicating SIP ACK was received on invite request. // This metaevent Will contain an IPSET_SDP/IPPARM_SDP_ANSWER in a inbound // invite/reinvite delayed offer call scenario. . . . break; . . .
PAGE 414
gc_ReqModifyCall( ) — request modification of call attributes gc_ReqModifyCall( ) request modification of call attributes Name: int gc_ReqModifyCall (crn, parmblkp, mode) Inputs: CRN crn • call reference number of call targeted for modification GC_PARM_BLK *parmblkp • pointer to GC_PARM_BLK which contains attributes of call requested for modifying unsigned long mode • completion mode (EV_ASYNC) Returns: 0 if successful <0 if unsuccessful Includes: gclib.
PAGE 415
request modification of call attributes — gc_ReqModifyCall( ) To set one or more message header fields in the re-INVITE request, the application inserts into the GC_PARM_BLK a parameter of the following form for each header field to be set: IPSET_SIP_MSGINFO IPPARM_SIP_HDR • value = string representing the complete header field, including field name Most SIP header fields that are valid in an INVITE request can be modified in a re-INVITE request without restriction.
PAGE 416
gc_ReqModifyCall( ) — request modification of call attributes To request a change in the attributes of a media session in 3PCC mode, a call control application explicitly constructs an SDP offer containing the desired new attributes, and then inserts it into the GC_PARM_BLK as a parameter element of the following type (see Section 5.2.2.
PAGE 417
request modification of call attributes — gc_ReqModifyCall( ) existing dialog or media session are performed and the current state remains as it was prior to the attempting the modification request. GCEV_CANCEL_MODIFY_CALL Successful termination event for a request to cancel a pending call modification request. Indicates that the remote UA accepted the CANCEL method and sent a 200OK, and the library automatically sent an ensuing ACK.
PAGE 418
gc_ReqModifyCall( ) — request modification of call attributes . . /* Dialogic Header Files */ #include #include . . . /* Request remote SIP client to change call to G.729: /* Assumes: 1) caller has verified call to be in connected state /* 2) caller has enabled event handler for GCEV_MODIFY_CALL_ACK, /* GCEV_MODIFY_CALL_REJ, and GCEV_MODIFY_CALL_FAIL.
PAGE 419
request modification of call attributes — gc_ReqModifyCall( ) /* Request remote SIP client to change call to G.729: /* Assumes: 1) caller has verified call to be in connected state int reqChangeToG729(CRN crn) { GC_PARM_BLK *parmblkp = NULL; */ */ char sdpG729[] = "v=0\r\n" \ "o=Dialogic_IPCCLib 146430240 146430241 IN IP4 169.254.00.01\r\n" \ "s=Dialogic_SIP_CCLLIB\r\n" \ "i=session information\r\n" \ "c=IN IP4 169.254.00.
PAGE 420
gc_ReqModifyCall( ) — request modification of call attributes gc_util_delete_parm_blk(parmblkp); } /* End of function. */ The following example illustrates the use of gc_ReqModifyCall( ) to refresh the Contact header: . . /* Dialogic Header Files */ #include #include . . . /* Request Contact refresh: /* Assumes: 1) caller has verified call to be in connected state /* 2) caller has enabled event handler for GCEV_MODIFY_CALL_ACK, /* GCEV_MODIFY_CALL_REJ, and GCEV_MODIFY_CALL_FAIL.
PAGE 421
set IP authentication information — gc_SetAuthenticationInfo( ) gc_SetAuthenticationInfo( ) set IP authentication information Name: int gc_SetAuthenticationInfo(target_type, target_id, infoparmblkp) Inputs: int target_type • type of target object (virtual board) long target_id • target object ID GC_PARM_BLKP infoparmblkp • pointer to GC_PARM_BLK with user information Returns: 0 if successful <0 if failure Includes: gclib.h gcerr.
PAGE 422
gc_SetAuthenticationInfo( ) — set IP authentication information a quadruplet that already exists, the existing username and password are overwritten with the new strings. If the identity field in the IP_AUTHENTICATION structure is an empty string, the function will set the specified username and password as the defaults for the specified realm.
PAGE 423
set IP authentication information — gc_SetAuthenticationInfo( ) void configureAuthQuadruplet (long boardDev) { GC_PARM_BLK *parmblkp = NULL; char realm[] = "example.com"; char identity[] = "sip:bob@example.com"; char username[] = "bob"; char password [] = "password1"; IP_AUTHENTICATION authentication; INIT_IP_AUTHENTICATION (&authentication); authentication.realm = realm; authentication.identity = identity; authentication.username = username; authentication.
PAGE 424
gc_SipAck( ) — acknowledge a SIP 200OK message in 3PCC mode gc_SipAck( ) acknowledge a SIP 200OK message in 3PCC mode Name: int gc_SipAck(crn, parmblk, mode) Inputs: CRN crn • call reference number of call targeted for modification GC_PARM_BLKP parmblk • pointer to optional parameter block containing SDP content for the SIP ACK message unsigned long mode • completion mode (EV_ASYNC) Returns: 0 if successful <0 if unsuccessful Includes: gclib.
PAGE 425
acknowledge a SIP 200OK message in 3PCC mode — gc_SipAck( ) Termination Events GCEV_SIP_ACK_OK Successful termination event for gc_SipAck( ) indicating that the ACK message was successfully sent GCEV_ SIP_ACK_FAILED Unsuccessful termination event for gc_SipAck( ) indicating that the ACK message could not be sent. The ACK message could not be sent because the dialog state was invalid for the ACK message generation.
PAGE 426
gc_SipAck( ) — acknowledge a SIP 200OK message in 3PCC mode /* SRL event handler: */ for (;;) { if (-1 != sr_waitevt(500)) process_event(); } void process_event(void) { METAEVENT metaevent; GC_INFO t_info; /* Populate the metaEvent structure */ if(GC_SUCCESS != gc_GetMetaEvent(&metaevent)) return; /* process GlobalCall events */ if ((metaevent.flags & GCME_GC_EVENT) == 0) return; switch (metaevent.evttype) { . . .
PAGE 427
acknowledge a SIP 200OK message in 3PCC mode — gc_SipAck( ) case GCEV_SIP_ACK_FAILED: /* process failure to change attribute */ if (gc_ResultInfo(&metaevent, &t_info) < 0) /* failure logic here */ /* process information contained in t_info */ . . . break; case GCEV_ACK: . . . /* local dialog transaction complete */ . . . break; . . .
PAGE 428
gc_util_copy_parm_blk( ) — copy the specified GC_PARM_BLK gc_util_copy_parm_blk( ) copy the specified GC_PARM_BLK Name: int gc_util_copy_parm_blk(parm_blkpp, parm_blkp) Inputs: GC_PARM_BLKP* parm_blkpp • pointer to the address of the new GC_PARM_BLK GC_PARM_BLKP parm_blkp • pointer to a valid GC_PARM_BLK to be copied Returns: GC_SUCCESS if successful GC_ERROR if unsuccessful Includes: gclib.h gcerr.
PAGE 429
copy the specified GC_PARM_BLK — gc_util_copy_parm_blk( ) Errors If this function returns GC_ERROR(-1) to indicate failure, use the gc_ErrorInfo( ) function to retrieve the reason for the error. See the “Error Handling” section in the Dialogic® Global Call API Programming Guide. All Global Call error codes are defined in the gcerr.h file. Example #include "gclib.h" #include "gcip.
PAGE 430
gc_util_find_parm_ex( ) — find a parameter in a GC_PARM_BLK gc_util_find_parm_ex( ) find a parameter in a GC_PARM_BLK Name: int gc_util_find_parm_ex(parm_blk, setID, parmID, parm) Inputs: GC_PARM_BLKP parm_blk • pointer to GC_PARM_BLK to search for the parameter unsigned long setID • parameter set ID of parameter to be found unsigned long parmID • parameter ID of parameter to be found GC_PARM_DATA_EXTP parm • pointer to a valid GC_PARM_DATA_EXT structure that identifies where in the parm block to s
PAGE 431
find a parameter in a GC_PARM_BLK — gc_util_find_parm_ex( ) GC_PARM_BLK, the function fills in the GC_PARM_DATA_EXT structure with the parameter data and returns GC_SUCCESS. If the parameter does not exist in the GC_PARM_BLK, or if no more parameters of the specified type are found, the function returns EGC_NO_MORE_PARMS. To search from the beginning of the GC_PARM_BLK, initialize the GC_PARM_DATA_EXT structure by using INIT_GC_PARM_DATA_EXT(parm) before calling gc_util_find_parm_ex( ).
PAGE 432
gc_util_find_parm_ex( ) — find a parameter in a GC_PARM_BLK /* Initialize this structure for two reasons: * 1. To search from the first parameter in the parm block * 2. The first time this structure is used it must be initialized */ INIT_GC_PARM_DATA_EXT(&parm_data_ext); /* loop to retrieve all of the parameters and associated data in the * GC_PARM_BLK that match the set_ID/parm_ID pair for SIP header fields.
PAGE 433
insert a GC_PARM_BLK parameter by reference — gc_util_insert_parm_ref_ex( ) gc_util_insert_parm_ref_ex( ) insert a GC_PARM_BLK parameter by reference Name: int gc_util_insert_parm_ref_ex(parm_blkpp, setID, parmID, data_size, datap) Inputs: GC_PARM_BLKP *parm_blkpp • pointer to the address of a valid GC_PARM_BLK unsigned long setID • set ID of parameter to be inserted unsigned long parmID • parm ID of parameter to be inserted unsigned long data_size • size in bytes of the parameter data void *datap
PAGE 434
gc_util_insert_parm_ref_ex( ) — insert a GC_PARM_BLK parameter by reference Parameter Description parm_blkpp points to the address of a valid GC_PARM_BLK where the parameter element is to be inserted. Set *parm_blkpp to NULL to insert the parameter into a new block. setID set ID of the parameter to be inserted parmID parameter ID of the parameter to be inserted data_size size, in bytes, of the value data associated with this parameter.
PAGE 435
insert a GC_PARM_BLK parameter by reference — gc_util_insert_parm_ref_ex( ) /* Pass the parm block to GC */ if ( gc_SetUserInfo( GCTGT_GCLIB_CRN, crn, &my_blkp, GC_SINGLECALL) != GC_SUCCESS ) { /* Process error */ } /* GC_PARM_BLK is no longer needed; delete the block */ gc_util_delete_parm_blk( my_blkp ); } See Also • gc_util_delete_parm_blk( ) • gc_util_insert_parm_ref( ) • gc_util_insert_parm_val( ) Dialogic® Global Call IP Technology Guide — November 2007 Dialogic Corporation 435
PAGE 436
gc_util_next_parm_ex( ) — retrieve the next parameter in a GC_PARM_BLK gc_util_next_parm_ex( ) retrieve the next parameter in a GC_PARM_BLK Name: int gc_util_next_parm_ex(parm_blk, parm ) Inputs: GC_PARM_BLKP parm_blk • pointer to GC_PARM_BLK GC_PARM_DATA_EXTP parm • pointer to valid GC_PARM_DATA_EXT structure identifying current parameter Outputs: GC_PARM_DATA_EXTP parm • pointer to GC_PARM_DATA_EXT structure containing retrieved next parameter Returns: GC_SUCCESS if successful EGC_NO_MORE_PARMS if
PAGE 437
retrieve the next parameter in a GC_PARM_BLK — gc_util_next_parm_ex( ) The gc_util_next_parm_ex( ) function updates the data structure referenced by the parm pointer and returns GC_SUCCESS if there is another parameter element in the GC_PARM_BLK following the element that was identified in the function call. If the current parameter data structure referenced by parm identifies the last parameter element in the GC_PARM_BLK, the next function call returns EGC_NO_MORE_PARMS.
PAGE 438
gc_util_next_parm_ex( ) — retrieve the next parameter in a GC_PARM_BLK { . . . } } /* Check for error */ if ( GC_ERROR == ret ) { /* Process error */ } . . .
PAGE 439
initialize GC_PARM_DATA_EXT structure — INIT_GC_PARM_DATA_EXT( ) INIT_GC_PARM_DATA_EXT( ) initialize GC_PARM_DATA_EXT structure Name: void INIT_GC_PARM_DATA_EXT(pData) Inputs: GC_PARM_DATA_EXT *pData • pointer to the structure to be initialized Returns: None Includes: gcip.
PAGE 440
INIT_GC_PARM_DATA_EXT( ) — initialize GC_PARM_DATA_EXT structure switch(parm_data_ext.set_ID); { . . . } } /* Check for error */ if ( GC_ERROR == ret ) { /* Process error */ } . . .
PAGE 441
initialize IP_VIRTBOARD data structure — INIT_IP_VIRTBOARD( ) INIT_IP_VIRTBOARD( ) initialize IP_VIRTBOARD data structure Name: void INIT_IP_VIRTBOARD(pIpVb) Inputs: IP_VIRTBOARD *pIpVb • pointer to the structure to be initialized Returns: None Includes: gcip.h Mode: synchronous Description The INIT_IP_VIRTBOARD( ) function is used to initialize an IP_VIRTBOARD data structure, which contains configuration data for a specific virtual IPT board.
PAGE 442
INIT_IP_VIRTBOARD( ) — initialize IP_VIRTBOARD data structure Example IP_VIRTBOARD ip_virtboard[2]; IPCCLIB_START_DATA ipcclibstart; INIT_IPCCLIB_START_DATA(&ipcclibstart, 2, ip_virtboard); INIT_IP_VIRTBOARD(&ip_virtboard[0]); INIT_IP_VIRTBOARD(&ip_virtboard[1]); ip_virtboard[0].sup_serv_mask = IP_SUP_SERV_CALL_XFER; /* override supp services default */ ip_virtboard[1].
PAGE 443
initialize IPCCLIB_START_DATA structure — INIT_IPCCLIB_START_DATA( ) INIT_IPCCLIB_START_DATA( ) initialize IPCCLIB_START_DATA structure Name: void INIT_IPCCLIB_START_DATA(pIpStData, numBoards, pIpVb) Inputs: IPCCLIB_START_DATA *pIpStData • pointer to the structure to be initialized unsigned char numBoards • number of boards IP_VIRTBOARD *pIpVb • pointer to an array of IP_VIRTBOARD structures Returns: None Includes: gcip.
PAGE 444
Dialogic® Global Call API Function Variances for IP 8.3 Note: Except for gc_Listen( ), gc_OpenEx( ), gc_ReleaseCallEx( ), gc_UnListen( ), all Dialogic® Global Call API functions that nominally support synchronous and asynchronous mode are supported only in asynchronous mode when using the IP technology. The Dialogic® Global Call API function variances that apply when using IP technology are described in the following sections.
PAGE 445
. /* Append/create GC_PARM_BLK with specified 183 response code*/ gc_util_insert_parm_val(&parmblkp, IPSET_SIP_RESPONSE_CODE, IPPARM_ACCEPT_RESP_CODE, sizeof(unsigned short, &acceptCode); rc = gc_SetConfigData(GCTGT_CCLIB_NETIF, boardDev, parmblkp, 0, GCUPDATE_IMMEDIATE, &request_id, EV_ASYNC); if (rc != GC_SUCCESS) { /* handle error */ } . . . 8.3.
PAGE 446
8.3.3 gc_AcceptXfer( ) Variances for IP This function is only available if the call transfer supplementary service was enabled via the sup_serv_mask field in the IP_VIRTBOARD structure when the board device was started. The parmblkp parameter is ignored for IP technology and should be set to NULL. The gc_AcceptXfer( ) function can be used at party B only after receiving a GCEV_REQ_XFER event.
PAGE 447
8.3.4 gc_AnswerCall( ) Variances for IP This function is only supported in asynchronous mode. The rings parameter is ignored. Coders can be set in advance of using gc_AnswerCall( ) by using gc_SetUserInfo( ). See Section 8.3.26, “gc_SetUserInfo( ) Variances for IP”, on page 487 for more information. The following code example shows how to use the gc_SetUserInfo( ) function to set coder information before calls are answered using gc_AnswerCall( ).
PAGE 448
Variance for H.323 The gc_AnswerCall( ) function is used to send the Q.931 CONNECT message to the originating endpoint. Variance for SIP The gc_AnswerCall( ) function is used to send the 200 OK message to the originating endpoint. 8.3.5 gc_CallAck( ) Variances for IP This function is only supported in asynchronous mode. The callack_blkp parameter must be a pointer to a GC_CALLACK_BLK structure that contains a type field with a value of GCACK_SERVICE_PROC.
PAGE 449
Variance for H.323 Allowable protocol-specific cause codes are prefixed by IPEC_H225 or IPEC_Q931 in Chapter 11, “IP-Specific Event Cause Codes”. Variance for SIP Cause codes and reasons are only supported when gc_DropCall( ) is issued while the call is in the Offered state. Allowable protocol-specific cause codes are prefixed by IPEC_SIP in Chapter 11, “IP-Specific Event Cause Codes”. Note: 8.3.
PAGE 450
Table 26. Valid Extension IDs for the gc_Extension( ) Function Extension ID IPEXTID_CHANGEMODE Description Used with gc_Extension( ) for the following T.38 fax server operations: • initiating a switch from an audio session to a T.38 fax session • initiating a switch from a T.38 fax session to an audio session • accepting a request to switch from audio to T.38 fax or vice versa • rejecting a request to switch from audio to T.
PAGE 451
Table 26. Valid Extension IDs for the gc_Extension( ) Function Extension ID IPEXTID_SEND_DTMF Description Used to send DTMF digits. When this call is successful, the sending side receives a GCEV_EXTENSIONCMPLT event with the same ext_id. The remote side receives a GCEV_EXTENSION event with IPEXTID_RECEIVE_DTMF but only when configured for notification of a specific type of DTMF. See Section 4.6.1, “Enabling and Disabling Unsolicited Notification Events”, on page 154 for more information.
PAGE 452
Dialogic® IP Media Library API Library Reference and the Dialogic® IP Media Library API Programming Guide for more information. The thresholds supported by Dialogic® Global Call API for HMP include: • QOSTYPE_LOSTPACKETS • QOSTYPE_JITTER • QOSTYPE_RTCPTIMEOUT • QOSTYPE_RTPTIMEOUT. mode Must be set to EV_SYNC. Note: Applications must include the gcipmlib.h header file before Dialogic® Global Call API can be used to set or retrieve QoS threshold values. See Section 4.21.
PAGE 453
define to allocate a buffer that is large enough to hold any type of Call ID value (i.e., either an H.323 array of octets or a SIP string). Note: For outbound calls the gc_GetCallInfo( ) function can be used to retrieve valid Call ID information only after the Proceeding state. The gc_GetCallInfo( ) function can also be used to query the protocol used by a call.
PAGE 454
When retrieving called party (DNIS) information, the address is taken from the SIP To: header, and is accessible in one of two forms by using one of the following parameter IDs in the function call: DESTINATION_ADDRESS Returns the simple destination address in the form user@127.0.0.1 DESTINATION_ADDRESS_SIP Returns a SIP-specific destination address that includes additional To URI parameters in the form sip: userB@127.0.0.
PAGE 455
8.3.11 gc_GetCTInfo( ) Variances for IP The gc_GetCTInfo( ) function can be used to retrieve product information (via the CT_DEVINFO structure) for the media sub-device (ipm) attached to the network device (ipt). If no media device is associated with the network device, the function returns as though not supported. 8.3.
PAGE 456
The parmblkp and ret_rerouting_infopp parameters are ignored and should be set to NULL. The gc_InitXfer( ) function returns -1 if invalid parameter are specified. Variance for H.323 (H.450.2) The gc_InitXfer( ) function has an associated GCEV_INIT_XFER termination event that is received on the specified CRN. This termination event indicates that the initiate transfer request was successful and that party C has sent a positive acknowledgement.
PAGE 457
Table 27. gc_InvokeXfer( ) Supported Parameters for H.450.2 (Continued) Parameter numberstr Meaning Ignored in supervised call transfer – set to NULL. For blind call transfer, used to provide address of party C (the rerouting address) as a string. Signaled to party B in the GCEV_REQ_XFER event. Format can be: • transport address, for example, “TA:146.152.0.1” • E.
PAGE 458
Table 29. H.450.2 ctIdentify Errors Received From the Network (Continued) ctIdentify Error Result Values supplementaryService InteractionNotAllowed CC: IPEC_H450TRTSESuppServInteractionNotAllowed unspecified GC Event GC: GCRV_REMOTEREJ_NOTALLOWED CC: IPECH4502TRTSEUnspecified GCEV_ INVOKE_XFER_REJ GCEV_ INVOKE_XFER_REJ GC: GCRV_REMOTEREJ_UNSPECIFIED Table 30. H.450.
PAGE 459
gc_SetConfigData(GCTGT_GCLIB_CHAN,ldev,t_pParmBlk,0,GCUPDATE_IMMEDIATE,&request_id,EV_SYNC); gc_util_delete_parm_blk(t_pParmBlk) The specific meaning of the GCEV_INVOKE_XFER termination event for successful transfers is dependant on the application and the transfer scenario(s) it uses.
PAGE 460
Fields”, on page 172. Table 33 lists the header fields that can be set in REFER messages and the corresponding parameter IDs along with examples of field values. Table 33. SIP Header Fields Settable in REFER Messages Field Name 8.3.16 GC Parameter ID (Set ID: IPSET_SIP_MSGINFO) Example Field Value Request URI IPPARM_REQUEST_URI 146.152.212.67:5060 From IPPARM_FROM From: Transferor ;tag=013c4-408c7921-1026900f-ed5;myname To IPPARM_TO To: Transferee
PAGE 461
A network device that is opened in multi-protocol mode defaults to IP_PROTOCOL_H323 if the protocol is not explicitly set in the makecall block. Note: Applications should not use the gc_SetUserInfo( ) function to set the IP protocol. When making calls on devices that support only one protocol, it is not necessary to include an IPSET_PROTOCOL element in the makecall block.
PAGE 462
Table 34. Configurable Call Parameters When Using H.323 (Continued) Set ID Parameter ID(s) and Data Types IPSET_CALLINFO See Section 9.2.2, “IPSET_CALLINFO”, on page 512 for more information. IPPARM_CONNECTIONMETHOD Enumeration, with one of the following values: • IP_CONNECTIONMETHOD_FASTSTART • IP_CONNECTIONMETHOD_SLOWSTART See Section 4.2.2, “H.323 Fast Start and Slow Start”, on page 116 for more information. IPPARM_CALLID Array of octets, length = MAX_IP_H323_CALLID_LENGTH IPPARM_DISPLAY String, max.
PAGE 463
Table 34. Configurable Call Parameters When Using H.323 (Continued) Set ID IPSET_NONSTANDARDDATA See Section 9.2.18, “IPSET_NONSTANDARDDATA”, on page 526 for more information. Parameter ID(s) and Data Types Either: • IPPARM_NONSTANDARDDATA_DATA String, max. length = MAX_NS_PARM_DATA_LENGTH (128) and • IPPARM_NONSTANDARDDATA_OBJID Unsigned Int[ ], max. length =MAX_NS_PARM_OBJID_LENGTH (40) or • IPPARM_NONSTANDARDDATA_DATA String, max.
PAGE 464
Table 35. Configurable Call Parameters When Using SIP Set ID GCSET_CHAN_CAPABILITY Note: This parameter set is not supported in 3PCC operating mode. Parameter ID and Datatype IPPARM_LOCAL_CAPABILITY Data structure, type IP_CAPABILITY. See reference page for IP_CAPABILITY on page 543 for more information. Note: If no transmit/receive coder type is specified, any supported coder type is accepted. IPSET_CALLINFO See Section 9.2.2, “IPSET_CALLINFO”, on page 512 for more information.
PAGE 465
8.3.17.3 Forming a Destination Address String Variance for H.323 The destination address is formed by concatenating values from three different sources: • the GC_MAKECALL_BLK • the numberstr parameter of gc_MakeCall( ) • the phone list The order or precedence of these elements and the rules for forming a destination address are described below. Notes: 1. The following description refers to a delimited string.
PAGE 466
Variance for SIP The format of the destination address for a SIP call is: user@host; param=value with the elements representing: user a user name or phone number host a domain name or an IP address param=value an optional additional parameter When making a SIP call, the destination address is formed according to the following rules in the order of precedence shown: 1.
PAGE 467
/* set GCLIB_ADDRESS_BLK with destination string & type*/ strcpy(gcmkbl.gclib->destination.address,pDestAddrBlk); gcmkbl.gclib->destination.address_type = GCADDRTYPE_TRANSPARENT; /* calling the function with the MAKECALL_BLK, and numberstr parameter=NULL the INVITE dest address will be: 11223344@127.0.0.
PAGE 468
8.3.17.4 Note: Destination Address Interpretation The following information applies when using H.323 only. Once a destination string is formed as described in the previous section, the H.323 stack treats the string according to the following rules: • The first section of the string is the destination of the next IP entity (for example, a gateway, terminal, the alias for a remote registered entity, etc.) with which the application attempts to negotiate. • A non-prefixed section in the string is the Q.
PAGE 469
char *pDestAddrBlk = "127.0.0.1"; char *pDestAddrStr = "TEL:111,TEL:222,76543"; /* set GCLIB_ADDRESS_BLK with destination string & type*/ strcpy(gcmkbl.gclib->destination.address,pDestAddrBlk); gcmkbl.gclib->destination.address_type = GCADDRTYPE_IP; gclib_mkbl.ext_datap = target_datap; /* calling the function with the MAKECALL_BLK*/ gc_MakeCall(ldev, &crn, pDestAddrStr, &gcmkbl, MakeCallTimeout,EV_ASYNC); Scenario 3 – Making a call to a known IP address, setting a number of H.
PAGE 470
/* set GCLIB_ADDRESS_BLK with destination string & type (H323-ID) */ strcpy(gcmkbl.gclib->destination.address,pDestAddrBlk); gcmkbl.gclib->destination.address_type = GCADDRTYPE_DOMAIN; gclib_mkbl.ext_datap = target_datap; /* calling the function with the MAKECALL_BLK */ gc_MakeCall(ldev, &crn, pDestAddrStr, &gcmkbl, MakeCallTimeout,EV_ASYNC); Scenario 6 – While registered, making a call, via the gatekeeper, to a registered entity (using a known e-mail address), setting a number of H.
PAGE 471
Note: 8.3.17.6 When using the H.323 protocol, the application may receive a timeout when trying to make an outbound call if network congestion is encountered and a TCP connection cannot be established. In this case, the SETUP message is not sent on the network. Code Examples H.323-Specific Code Example The following code example shows how to make a call using the H.323 protocol.
PAGE 472
/* initialize IP_CAPABILITY structure */ IP_CAPABILITY t_Capability = {0}; /* configure a GC_PARM_BLK with four coders, display, phone list and UUI message: */ /* specify and insert first capability parameter data for G.7231 coder */ t_Capability.type = GCCAPTYPE_AUDIO; t_Capability.direction = IP_CAP_DIR_LCLTRANSMIT; t_Capability.extra.audio.VAD = GCPV_DISABLE; t_Capability.extra.audio.frames_per_pkt = 1; t_Capability.
PAGE 473
/* insert phone list */ rc = gc_util_insert_parm_ref(&target_datap, IPSET_CALLINFO, IPPARM_PHONELIST, (unsigned char)(strlen(IpPhoneList)+1), IpPhoneList); /* insert user to user information */ rc = gc_util_insert_parm_ref(&target_datap, IPSET_CALLINFO, IPPARM_USERUSER_INFO, (unsigned char)(strlen(IpUUI)+1), IpUUI); /* setting NS Data elements */ gc_util_insert_parm_ref_ex(&target_datap, IPSET_NONSTANDARDDATA, IPPARM_NONSTANDARDDATA_DATA, (unsigned long)(strlen(IpNSDataData)+1), IpNSDataData); if(ChoiceOfNS
PAGE 474
if(rc == 0) { gclib_mkbl.ext_datap = target_datap; rc = gc_MakeCall(ldev, &crn, pDestAddrStr, &gcmkbl, MakeCallTimeout, EV_ASYNC); /* deallocate GC_PARM_BLK pointer */ gc_util_delete_parm_blk(target_datap); } } SIP-Specific Code Example The following code example shows how to make a call using the SIP protocol. /* Make a SIP IP call on line device ldev */ void MakeSipIpCall(LINEDEV ldev) { char *IpDisplay = "This is a Display"; /* display data */ char *pDestAddrBlk = "12345@127.0.0.
PAGE 475
t_Capability.type = GCCAPTYPE_AUDIO; t_Capability.direction = IP_CAP_DIR_LCLRECEIVE; t_Capability.extra.audio.VAD = GCPV_DISABLE; t_Capability.extra.audio.frames_per_pkt = 1; t_Capability.capability = GCCAP_AUDIO_g7231_6_3k; rc = gc_util_insert_parm_ref(&target_datap, GCSET_CHAN_CAPABILITY, IPPARM_LOCAL_CAPABILITY, sizeof(IP_CAPABILITY), &t_Capability); /* specify and insert second capability parameter data for G.
PAGE 476
8.3.18 gc_OpenEx( ) Variances for IP The gc_OpenEx( ) function is supported in both synchronous and asynchronous mode, but the use of asynchronous mode is recommended. The procedure for opening devices is the same regardless of whether H.323 or SIP is used. The IPT network device (N_ipt_BxTy) and IP Media device (M_ipmBxCy) can be opened in the same gc_OpenEx( ) call and a voice device (V_dxxxBwCz) can also be included.
PAGE 477
An IPT network device (iptBx) can also used for host LAN disconnect alarms. Note that all other Dialogic® Global Call API alarms for IP are reported on IP Media (ipm) devices, not IPT network (ipt) devices. Note: Applications should avoid closing and re-opening devices multiple times. Board devices and channel devices should be opened during initialization and should remain open for the duration of the application.
PAGE 478
Variance for SIP This function does not apply to SIP call transfer. The SIP stack does not contact the Transfer Target or Transferred-To party (party C) until party A calls gc_InvokeXfer( ), so there is no issue of accepting or rejecting the transfer at the initiation stage. 8.3.20 gc_RejectXfer( ) Variances for IP This function is only available if the call transfer supplementary service was enabled via the sup_serv_mask field in the IP_VIRTBOARD structure when the board device was started.
PAGE 479
8.3.22 gc_ReqService( ) Variances for IP This function is only supported in asynchronous mode. The gc_ReqService( ) function can be used to register an endpoint with a registration server (gateway in H.323 or registrar in SIP).
PAGE 480
Deregister options are specified by inserting the following parameter element into the GC_PARM_BLK referenced by reqdatap: IPSET_REG_INFO IPPARM_OPERATION_DEREGISTER and one of the following parameter data values: • IP_REG_MAINTAIN_LOCAL_INFO – deregister and keep the registration information locally • IP_REG_DELETE_ALL – deregister and discard the local registration information See Section 4.22.4.2, “Deregistration Example”, on page 283 for more information.
PAGE 481
Table 38. Registration Information When Using H.323 (Continued) Set ID IPSET_REG_INFO See Section 9.2.20, “IPSET_REG_INFO”, on page 527, for more information.
PAGE 482
Table 39. Registration Information When Using SIP Set ID Parameter IDs GCSET_SERVREQ PARM_REQTYPE † • Value = IP_REQTYPE_REGISTRATION GCSET_SERVREQ PARM_ACK † IPSET_LOCAL_ALIAS IPPARM_ADDRESS_DOT_NOTATION IPPARM_ADDRESS_EMAIL IPPARM_ADDRESS_TRANSPARENT Data type: String IPSET_PROTOCOL IPPARM_PROTOCOL_BITMASK Bitmask composed from one or both of the following values: • IP_PROTOCOL_H323 • IP_PROTOCOL_SIP IPSET_REG_INFO See Section 9.2.20, “IPSET_REG_INFO”, on page 527, for more information.
PAGE 483
The following are the relevant function parameters: target_type GCTGT_CCLIB_NETIF target_id IPT board device datap pointer to GC_PARM_BLK with additional response information Because some of the data may be protocol specific (in future releases), there is a facility to set the protocol type using the following IP parameter element in the GC_PARM_BLK, datap: IPSET_PROTOCOL IPPARM_PROTOCOL_BITMASK and one of the following parameter data values: • IP_PROTOCOL_H323 • IP_PROTOCOL_SIP • IP_PROTOCOL_H323 | IP_PROT
PAGE 484
in the Dialogic® IP Media Library API Library Reference and the Dialogic® IP Media Library API Programming Guide for more information. The thresholds supported by Dialogic® Global Call API for HMP are: • QOSTYPE_JITTER • QOSTYPE_LOSTPACKETS • QOSTYPE_RTCPTIMEOUT • QOSTYPE_RTPTIMEOUT mode Must be set to EV_SYNC. Note: Applications must include the gcipmlib.h header file before Dialogic® Global Call API can be used to set or retrieve QoS threshold values. See Section 4.21.
PAGE 485
When using the gc_SetConfigData( ) function on a board device (the first three bullets above), use the following function parameter values: target_type GCTGT_CCLIB_NETIF target_id An IPT board device that can be obtained by using the gc_OpenEx( ) function with :N_iptBx:P_IP in the devicename parameter. See Section 8.3.18, “gc_OpenEx( ) Variances for IP”, on page 476 for more information. target_datap A pointer to a GC_PARM_BLKP structure that contains the parameters to be configured.
PAGE 486
Table 40. Parameters Configurable Using gc_SetConfigData( ) When Using H.
PAGE 487
to use is GCSET_CALLEVENT_MSK, and the parameter IDs that may be used are GCACT_ADDMSK, GCACT_SUBMSK, and GCACT_SETMSK. The specific parameter value that is used to enable or disable the GCEV_INVOKE_XFER_ACCEPTED event is GCMSK_INVOKE_XFER_ACCEPTED. Note that there is no corresponding event for H.450.2 call transfers. Table 41 describes the call parameters that can be included in the GC_PARM_BLK associated with the gc_SetConfigData( ) function.
PAGE 488
• set SIP message information fields • set IP Media Library parameters (for example, echo cancellation parameters) for a specified line device • associate and disassociate a T.38 Fax device with a Media device The gc_SetUserInfo( ) function is used to set the values of call-related information, such as coder information, display information, phone list, etc. before a call has been initiated.
PAGE 489
target_id CRN (if it exists) or line device (if a CRN does not exist) duration GC_SINGLECALL infoparmblkp a pointer to a GC_PARM_BLK with a list of parameters (including coder information) to be set for the line device. Note: 8.3.26.2 If a call is in the Null state, the new parameter values apply to the next call. If a call is in a non-Null state, the new parameter values apply to the remainder of the current call only.
PAGE 490
• • • • • • • • • • • • • • • • • • IPPARM_CONTACT_DISPLAY (deprecated) IPPARM_CONTACT_URI (deprecated) IPPARM_CONTENT_DISPOSITION (deprecated) IPPARM_CONTENT_ENCODING (deprecated) IPPARM_CONTENT_LENGTH (deprecated) IPPARM_CONTENT_TYPE (deprecated) IPPARM_DIVERSION_URI (deprecated) IPPARM_EVENT_HDR (deprecated) IPPARM_EXPIRES_HDR (deprecated) IPPARM_FROM (deprecated) IPPARM_FROM_DISPLAY (deprecated) IPPARM_REFER_TO (deprecated) IPPARM_REFERRED_BY (deprecated) IPPARM_REPLACES (deprecated) IPPARM_REQUEST_URI
PAGE 491
See Section 4.26.3, “Initiating a Switch from Audio to T.38 Fax”, on page 322 for more information and a code example. 8.3.27 gc_Start( ) Variances for IP The gc_Start( ) function is used to configure the Dialogic® Global Call API library on a system level and on a virtual board level. At the system level, the following items can be configured: • the number of IPT board devices (virtual boards) to create in the system (see Section 2.3.
PAGE 492
override the default value for any fields in any of these data structures to configure the virtual boards as desired. After the fields in the IPCCLIB_START_DATA and IP_VIRTBOARD structures have been configured, the IPCCLIB_START_DATA structure is passed to gc_Start( ) via pointers in CCLIB_START_STRUCT and GC_START_STRUCT data structures.
PAGE 493
2016 devices available (total_max_calls = 2016, three Dialogic® IPT boards), you can specify that all 2016 devices can be used for both H.323 calls and SIP calls (h323_max_calls = sip_max_calls = 2016), or half are used for H.323 only (h323_max_calls = 1008) and half are used for SIP only (sip_max_calls = 1008), or any other such combination. The only restriction is that total_max_calls must not exceed the sum of the other two parameters.
PAGE 494
The following parameters set in IP_VIRTBOARD for the default virtual board apply to both protocols: • total_max_calls = 120 • localIP.ip_ver = IPVER4 • localIP.u_ipaddr.ipv4 — set via DCM configuration manager utility • sup_serv_mask = IP_SUP_SERV_DISABLED The following parameters set in IP_VIRTBOARD for the default virtual board apply to H.
PAGE 495
8.3.29 gc_UnListen( ) Variances for IP The gc_UnListen( ) function is supported in both synchronous and asynchronous modes. The function is blocking in synchronous mode. Note: 8.4 For line devices that comprise media (ipm) and voice (dxxx) devices, routing is only done on the media devices. Routing of the voice devices must be done using the Voice API (dx_ functions).
PAGE 496
• GCEV_ACCEPT_MODIFY_CALL_FAIL (supported in SIP only) • GCEV_ACCEPT_XFER • GCEV_ACCEPT_XFER_FAIL • GCEV_ACKCALL (deprecated; equivalent is GCEV_CALLPROC) • GCEV_ALARM • GCEV_ALERTING (maskable event) • GCEV_ANSWERED • GCEV_ATTACH (not supported in 3PCC operating mode) • GCEV_ATTACHFAIL (not supported in 3PCC operating mode) • GCEV_BLOCKED • GCEV_CANCEL_MODIFY_CALL (supported in SIP only) • GCEV_CANCEL_MODIFY_CALL_FAIL (supported in SIP only) • GCEV_CONNECTED • GCEV_CALLPROC • GCEV_DETECTED (maskable event)
PAGE 497
• GCEV_OPENEX_FAIL • GCEV_PROCEEDING (maskable event) • GCEV_REQ_MODIFY_CALL (supported in SIP only) • GCEV_REQ_MODIFY_UNSUPPORTED (supported in SIP only) • GCEV_REJ_INIT_XFER (supported in H.323/H.450.2 only) • GCEV_REJ_INIT_XFER_FAIL (supported in H.323/H.450.2 only) • GCEV_REJ_XFER • GCEV_REJ_XFER_FAIL • GCEV_REJECT_MODIFY_CALL (supported in SIP only) • GCEV_REJECT_MODIFY_CALL_FAIL (supported in SIP only) • GCEV_RELEASECALL • GCEV_REQ_INIT_XFER (supported in H.323/H.450.
PAGE 498
Dialogic® Global Call IP Technology Guide — November 2007 Dialogic Corporation
PAGE 499
9 IP-Specific Parameters 9. This chapter describes the Dialogic® Global Call API parameter set IDs and parameter IDs (parm IDs) that are used with IP technology. Topics include: • Overview of Parameter Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499 • Parameter Set Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 500
IP-Specific Parameters Table 42. Summary of Parameter Sets and Parameter Usage (Continued) Set ID IPSET_ CALLINFO Parameter ID Set Send Retrieve SIP/ H.323 IPPARM_ BEARERCAP gc_SetUserInfo( ) (GC_SINGLECALL only) gc_MakeCall( ) from GCEV_OFFERED via gc_GetMetaEvent( ) H.
PAGE 501
IP-Specific Parameters Table 42. Summary of Parameter Sets and Parameter Usage (Continued) Set ID IPSET_ CALLINFO Parameter ID IPPARM_ PROGRESS_IND Set --- Send --- Retrieve gc_GetMetaEvent( ) (GCEV_EXTENSION) SIP/ H.323 H.323 only Note: Extension events for Progress messages are masked by default.
PAGE 502
IP-Specific Parameters Table 42. Summary of Parameter Sets and Parameter Usage (Continued) Set ID Parameter ID Set Send Retrieve SIP/ H.323 IPPARM_ DTMF_ ALPHANUMERIC --- gc_Extension( ) (IPEXTID_SEND_ DTMF) gc_Extension( ) (IPEXTID_ RECEIVE_DTMF) H.323, SIP 1PCC IPPARM_ DTMF_RFC2833_ PAYLOAD_TYPE gc_SetConfigData( ) gc_SetUserInfo( ) † --- --- H.323, SIP 1PCC IPPARM_ SUPPORT_DTMF_ BITMASK gc_SetConfigData( ) gc_SetUserInfo( ) † --- --- H.
PAGE 503
IP-Specific Parameters Table 42. Summary of Parameter Sets and Parameter Usage (Continued) Set ID IPSET_ LOCAL_ALIAS IPSET_ MEDIA_STATE Parameter ID Set Send Retrieve SIP/ H.323 IPPARM_ ADDRESS_ DOT_NOTATION --- gc_ReqService( ) --- both IPPARM_ ADDRESS_EMAIL --- gc_ReqService( ) --- both IPPARM_ ADDRESS_H323_ID --- gc_ReqService( ) --- H.323 only IPPARM_ ADDRESS_PHONE --- gc_ReqService( ) --- H.
PAGE 504
IP-Specific Parameters Table 42. Summary of Parameter Sets and Parameter Usage (Continued) Set ID Parameter ID Set Send Retrieve SIP/ H.
PAGE 505
IP-Specific Parameters Table 42. Summary of Parameter Sets and Parameter Usage (Continued) Set ID Parameter ID Set Send Retrieve SIP/ H.323 IPPARM_ H221NON STANDARD gc_SetConfigData( ) gc_MakeCall( ) gc_SetUserInfo( ) † gc_AnswerCall( ) gc_MakeCall( ) gc_Extension( ) (IPEXTID_GETINFO) H.323 only IPPARM_ NONSTANDARD DATA_DATA gc_SetConfigData( ) gc_SetUserInfo( ) † gc_MakeCall( ) gc_AnswerCall( ) gc_MakeCall( ) gc_DropCall( ) gc_ReqService( ) gc_Extension( ) (IPEXTID_GETINFO) H.
PAGE 506
IP-Specific Parameters Table 42. Summary of Parameter Sets and Parameter Usage (Continued) Set ID IPSET_RTP_ ADDRESS IPSET_SDP Parameter ID Set Retrieve SIP/ H.
PAGE 507
IP-Specific Parameters Table 42. Summary of Parameter Sets and Parameter Usage (Continued) Set ID IPSET_SIP_ MSGINFO IPSET_ SIP_REQUEST_ ERROR Parameter ID Set Send Retrieve SIP/ H.
PAGE 508
IP-Specific Parameters Table 42. Summary of Parameter Sets and Parameter Usage (Continued) Set ID IPSET_ SIP_ RESPONSE_ CODE IPSET_ SUPPORTED_ PREFIXES IPSET_ SWITCH_ CODEC Parameter ID Set Send Retrieve SIP/ H.323 IPPARM_ACCEPT_ RESP_CODE gc_SetConfigData( ) --- --- SIP only IPPARM_BUSY_ REASON gc_SetConfigData( ) --- --- SIP only IPPARM_RECEIVED_ RESPONSE_ STATUS_CODE --- --- GCEV_ALERTING SIP only IPPARM_ ADDRESS_DOT_ NOTATION --- gc_ReqService( ) --- H.
PAGE 509
IP-Specific Parameters Table 42. Summary of Parameter Sets and Parameter Usage (Continued) Set ID Parameter ID Set Send Retrieve SIP/ H.323 IPSET_ TRANSACTION IPPARM_ TRANSACTION_ID --- --- gc_Extension( ) (Any ext_id) both IPSET_ TUNNELED SIGNALMSG IPPARM TUNNELEDSIGNAL MSG_ALTERNATEID GC_MAKECALL_BLK for gc_MakeCall( ) gc_MakeCall( ), gc_CallAck( ), gc_AcceptCall( ), gc_AnswerCall( ), gc_DropCall( ), GCEV_ EXTENSIONCMPLT (IPEXTID_ RECEIVEMSG) H.
PAGE 510
IP-Specific Parameters Table 42.
PAGE 511
IP-Specific Parameters • IPSET_LOCAL_ALIAS • IPSET_MEDIA_STATE • IPSET_MIME and IPSET_MIME_200OK_TO_BYE • IPSET_MSG_H245 • IPSET_MSG_Q931 • IPSET_MSG_REGISTRATION • IPSET_MSG_SIP • IPSET_NONSTANDARDCONTROL • IPSET_NONSTANDARDDATA • IPSET_PROTOCOL • IPSET_REG_INFO • IPSET_RTP_ADDRESS • IPSET_SDP • IPSET_SIP_MSGINFO • IPSET_SIP_REQUEST_ERROR • IPSET_SIP_RESPONSE_CODE • IPSET_SUPPORTED_PREFIXES • IPSET_SWITCH_CODEC • IPSET_TRANSACTION • IPSET_TUNNELEDSIGNALMSG • IPSET_VENDORINFO 9.2.
PAGE 512
IP-Specific Parameters 9.2.2 IPSET_CALLINFO Table 44 shows the parameter IDs in the IPSET_CALLINFO parameter set. Table 44. IPSET_CALLINFO Parameter Set Parameter ID IPPARM_BEARERCAP Data Type & Size Type: string † Description Bearer Capability IE H.323 only Duration of the call H.323 only Globally unique identifier (Call ID) used by the underlying protocol to identify the call both Size: max.
PAGE 513
IP-Specific Parameters Table 44. IPSET_CALLINFO Parameter Set (Continued) Parameter ID IPPARM_H245TUNNELING Data Type & Size Type: enumeration Size: sizeof(char) Values: • IP_H245TUNNELING_ON Description SIP/ H.323 Specify if tunneling is on or off. For details, see Section 4.1.3, “Enabling and Disabling H.245 Tunneling (H.323)”, on page 114. H.323 only MediaWaitForConnect field in SETUP message. H.
PAGE 514
IP-Specific Parameters Table 44. IPSET_CALLINFO Parameter Set (Continued) Parameter ID IPPARM_PROGRESS_IND Data Type & Size Type: string † Size: max. length = 255 Description Progress Indicator IE in incoming PROGRESS messages. SIP/ H.323 H.323 only Note: Extension events for PROGRESS messages are masked by default. Enable via gc_SetUserInfo( ) with parameter IPSET_ EXTENSIONEVT_MSK, GCACT_SETMSK, EXTENSIONEVT_CALL_ PROGRESS) IPPARM_USERUSER_INFO Type: unsigned char[ ] User-to-user information H.
PAGE 515
IP-Specific Parameters Table 45. IPSET_CONFERENCE Parameter Set (Continued) Parameter ID IPPARM_CONFERENCE_ID Data Type & Size Type: string † Size: max. length = IP_CONFERENCE_ID_LENGTH (16) Description SIP/ H.323 The conference identifier H.323 only 1. For parameters with data of type String, the length in a GC_PARM_BLK is the length of the data string plus 1. 2. Conference ID retrieval is only relevant when an application is in a conference.
PAGE 516
IP-Specific Parameters Table 46. IPSET_CONFIG Parameter Set (Continued) Parameter ID IPPARM_OPERATING_MODE Data Type & Size Type: int Size: sizeof(int) Description Sets the method used to transition to/ from T.38 fax mode in 1PCC mode; also enables/disables access to SIP re-INVITE messages in both 1PCC and 3PCC modes. Possible values are: SIP/ H.323 both • IP_T38_AUTOMATIC_MODE – Default mode. A request to transition to or from T.
PAGE 517
IP-Specific Parameters 9.2.5 IPSET_DTMF Table 47 shows the parameter IDs in the IPSET_DTMF parameter set. This parameter set is used to set DTMF-related parameters for the notification, suppression or sending of DTMF digits. This parameter set is not supported in SIP third party call control (3PCC) operating mode. Table 47. IPSET_DTMF Parameter Set SIP/ H.
PAGE 518
IP-Specific Parameters 9.2.6 IPSET_EXTENSIONEVT_MSK This parameter set is used to enable or disable the events associated with unsolicited notification such as the detection of DTMF or a change of connection state in an underlying protocol. Table 48 shows the parameter IDs in the IPSET_EXTENSIONEVT_MSK parameter set. Table 48. IPSET_EXTENSIONEVT_MSK Parameter Set Parameter IDs GCPARM_GET_MSK Data Type & Size Type: int Description SIP/ H.
PAGE 519
IP-Specific Parameters 9.2.8 IPSET_H323_RESPONSE_CODE This parameter set is used to set the busy cause code that is used in the failure message sent when the local system is unable to accept additional incoming sessions. Table 50. IPSET_H323_RESPONSE_CODE Parameter Set Parameter ID Data Type & Size IPPARM_ BUSY_CAUSE Type: eIP_EC_TYPE Size: sizeof(int) Description Used in a GC_PARM_BLK to specify the cause code to send when no additional incoming sessions can be accepted. Values: SIP/ H.323 H.
PAGE 520
IP-Specific Parameters 9.2.10 IPSET_LOCAL_ALIAS Table 52 shows the parameter IDs in the IPSET_LOCAL_ALIAS parameter set. Table 52. IPSET_LOCAL_ALIAS Parameter Set Parameter IDs Data Type & Size IPPARM_ ADDRESS_DOT_NOTATION Type: string † IPPARM_ ADDRESS_EMAIL Type: string † Description SIP/ H.323 A valid IP address both e-mail address composed of characters from the set “[A-Z][a-z][0-9]_-.@” both Size: max. length = 255 IPPARM_ ADDRESS_H323_ID Type: string † A valid H.323 ID H.
PAGE 521
IP-Specific Parameters 9.2.11 IPSET_MEDIA_STATE Table 53 shows the parameter IDs in the IPSET_MEDIA_STATE parameter set. These parameters dispatched to the application in GCEV_EXTENSION events of type IPEXTID_MEDIAINFO. In all cases where the parameter data is an IP_CAPABILITY structure, the structure contains the coder capabilities that were negotiated with the remote peer. This parameter set is not supported in the SIP third party call control (3PCC) operating mode. Table 53.
PAGE 522
IP-Specific Parameters 9.2.12 IPSET_MIME and IPSET_MIME_200OK_TO_BYE Table 54 shows the parameter IDs in the IPSET_MIME and IPSET_MIME_200OK_TO_BYE parameter sets which are used when sending and receiving MIME-encoded SIP messages. The same parameters apply to both parameter sets. When using the IPSET_MIME_200OK_TO_BYE parameter set ID, that same set ID must be used in all parameter elements in all data blocks associated with the message. Table 54.
PAGE 523
IP-Specific Parameters 9.2.13 IPSET_MSG_H245 Table 55 shows the parameter IDs in the IPSET_MSG_H245 parameter set. This parameter set is used with the gc_Extension( ) and the IPEXTID_SENDMSG extension and encapsulates all the parameters required to send an H.245 message. Table 55. IPSET_MSG_H245 Parameter Set Parameter IDs IPPARM_MSGTYPE Data Type & Size Type: int Size: sizeof(int) 9.2.14 Description Possible values for H.245 messages are: • IP_MSGTYPE_H245_INDICATION SIP/ H.323 H.
PAGE 524
IP-Specific Parameters 9.2.16 IPSET_MSG_SIP Table 58 shows the parameter IDs in the IPSET_MSG_SIP parameter set. This parameter set is used to set the response code or message type for outgoing SIP messages. In most cases, the parameter set is also used to identify the message type for SIP messages that are passed to the application in Global Call events. Table 58.
PAGE 525
IP-Specific Parameters 9.2.17 IPSET_NONSTANDARDCONTROL Table 59 shows the parameter IDs in the IPSET_NONSTANDARDCONTROL parameter set. Table 59. IPSET_NONSTANDARDCONTROL Parameter Set Parameter IDs Data Type & Size IPPARM_ NONSTANDARDDATA_DATA Type: string † IPPARM_ NONSTANDARDDATA_OBJID Type: Uint[ ] IPPARM_H221NONSTANDARD Type: IP_H221NONSTANDARD Size: max. length = max_parm_data_size ‡ (configured at start-up via IPCCLIB_START_DATA) Size: max.
PAGE 526
IP-Specific Parameters 9.2.18 IPSET_NONSTANDARDDATA Table 60 shows the parameter IDs in the IPSET_NONSTANDARDDATA parameter set. Table 60. IPSET_NONSTANDARDDATA Parameter Set Parameter IDs Data Type & Size IPPARM_ NONSTANDARDDATA_DATA Type: string † IPPARM_ NONSTANDARDDATA_OBJID Type: Uint[ ] IPPARM_H221NONSTANDARD Type: IP_H221NONSTANDARD Size: max. length = max_parm_data_size ‡ (configured at start-up via IPCCLIB_START_DATA) Size: max.
PAGE 527
IP-Specific Parameters 9.2.20 IPSET_REG_INFO Table 62 shows the parameter IDs in the IPSET_REG_INFO parameter set. Table 62. IPSET_REG_INFO Parameter Set Parameter IDs IPPARM_OPERATION_ REGISTER Data Type & Size Type: char Size: sizeof(char) Description Used to specify the type of registration operation to perform with a gatekeeper or registrar. Possible values are: SIP/ H.
PAGE 528
IP-Specific Parameters 9.2.21 IPSET_RTP_ADDRESS Table 62 shows the parameter IDs in the IPSET_RTP_ADDRESS parameter set. Table 63. IPSET_RTP_ADDRESS Parameter Set Parameter IDs IPPARM_LOCAL Data Type & Size Type: int Size: sizeof(int) IPPARM_REMOTE Type: int Size: sizeof(int) 9.2.22 Description SIP/ H.323 Used when retrieving RTP address of the local endpoint of an RTP stream as contained in a connection event.
PAGE 529
IP-Specific Parameters Table 64. IPSET_SDP Parameter Set Data Type & Size Parameter IDs IPPARM_ SDP_ANSWER Type: string † IPPARM_ SDP_OFFER Type: string † IPPARM_ SDP_OPTION_ ANSWER Type: string † IPPARM_ SDP_OPTION_ OFFER Type: string † SIP/ H.323 Description Identifies parameter data as an SDP answer. SIP 3PCC only Identifies parameter data as an SDP offer. SIP 3PCC only Identifies parameter data as an SDP answer being exchanged in an OPTIONS transaction (e.g.
PAGE 530
IP-Specific Parameters Table 65.
PAGE 531
IP-Specific Parameters Table 65. IPSET_SIP_MSGINFO Parameter Set (Continued) Parameter IDs Data Type & Size IPPARM_TO_DISPLAY (deprecated) Type: string † IPPARM_TO (deprecated) Type: string † Description Size: max length = IP_TO_DISPLAY_MAXLEN Size: max length = IP_TO_MAXLEN SIP/ H.
PAGE 532
IP-Specific Parameters 9.2.25 IPSET_SIP_RESPONSE_CODE This parameter set is used for response codes that are contained in used in certain SIP response messages. When setting a response code, the code is set on the board device level by inserting this parameter in a GC_PARM_BLK and calling gc_SetConfigData( ). When receiving a response code, the parameter is contained in a GC_PARM_BLK associated with a Global Call event. Table 67.
PAGE 533
IP-Specific Parameters 9.2.26 IPSET_SUPPORTED_PREFIXES Table 68 shows the parameter IDs in the IPSET_SUPPORTED_PREFIXES parameter set. Table 68. IPSET_SUPPORTED_PREFIXES Parameter Set Parameter IDs Data Type & Size IPPARM_ ADDRESS_DOT_NOTATION Type: string † IPPARM_ ADDRESS_EMAIL Type: string † Description SIP/ H.323 A valid IP address in dot notation H.323 only Size: max. length = 255 An e-mail address composed of characters from the set “[A-Z][a-z][0-9]_-.@” H.
PAGE 534
IP-Specific Parameters Table 69. IPSET_SWITCH_CODEC Parameter Set (Continued) Parameter IDs IPPARM_AUDIO_REQUESTED Data Type & Size Type: int Size: sizeof(int) IPPARM_READY Type: int Size: sizeof(int) IPPARM_REJECT Type: int Size: sizeof(int) IPPARM_T38_INITIATE Type: int Size: sizeof(int) IPPARM_T38_REQUESTED Type: int Size: sizeof(int) 9.2.28 Description SIP/ H.323 Provides notification of an incoming request to switch from T.38 fax to audio. H.
PAGE 535
IP-Specific Parameters 9.2.29 IPSET_TUNNELEDSIGNALMSG Table 71 shows the parameter IDs in the IPSET_TUNNELEDSIGNALMSG parameter set, which is used when sending or receiving tunneled signaling messages (TSMs) in the H.323 protocol. Table 71. IPSET_TUNNELEDSIGNALMSG Parameter Set Parameter IDs IPPARM_ TSM_CONTENT_EVENT Description SIP/ H.323 Used to identify the type of Global Call event to retrieve TSM content from. Values include: H.
PAGE 536
IP-Specific Parameters Table 71. IPSET_TUNNELEDSIGNALMSG Parameter Set (Continued) Parameter IDs Data Type & Size IPPARM_ TUNNELEDSIGNALMSG_ NSDATA_OBJID Type: string † IPPARM_ TUNNELEDSIGNALMSG_ PROTOCOL_OBJECTID Type: IP_TUNNEL PROTOCOL_ OBJECTID Size: max length = MAX_NS_ PARAM_OBJID_ LENGTH (40) Size: sizeof( IP_TUNNEL PROTOCOL_ OBJECTID) IPPARM_ TUNNELEDSIGNALMSG_ PROTOCOL_OBJID Type: string † Size: max length = MAX_TSM_ POID_PARAM_ LENGTH (128) Description SIP/ H.
PAGE 537
IP-Specific Data Structures 10. 10 This chapter describes the data structures that are specific to IP technology. Note: These data structures are defined in the gcip.h header file. • GC_PARM_DATA_EXT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538 • IP_ADDR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540 • IP_AUDIO_CAPABILITY . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 538
GC_PARM_DATA_EXT — retrieved parameter data GC_PARM_DATA_EXT retrieved parameter data typedef struct { unsigned long version; void* pInternal; unsigned long set_ID; unsigned long parm_ID; unsigned long data_size; void* pData; }GC_PARM_DATA_EXT, *GC_PARM_DATA_EXTP; Description The GC_PARM_DATA_EXT structure contains parameter data retrieved from a GC_PARM_BLK by the gc_util_find_parm_ex( ) and gc_util_next_parm_ex( ) functions.
PAGE 539
retrieved parameter data — GC_PARM_DATA_EXT pInternal pointer used to identifythe paramter’s position within the GC_PARM_BLK structure. This field is reserved for library use and should not be used or modified by applications.
PAGE 540
IP_ADDR — local IP address IP_ADDR local IP address typedef struct { unsigned char union { unsigned int unsigned int }u_ipaddr; }IP_ADDR, *IP_ADDRP; ip_ver; ipv4; ipv6[4] Description The IP_ADDR structure is used to specify a local IP address. Field Descriptions The fields of the IP_ADDR data structure are described as follows: ip_ver The version of the local IP address. Possible values are: • IPVER4 u_ipaddr A union that contains the actual address.
PAGE 541
basic audio capability information — IP_AUDIO_CAPABILITY IP_AUDIO_CAPABILITY basic audio capability information typedef struct { unsigned long frames_per_pkt; long VAD; } IP_AUDIO_CAPABILITY; Description The IP_AUDIO_CAPABILITY data structure is used to allow some minimum set of information to be exchanged together with the audio codec identifier.
PAGE 542
IP_AUTHENTICATION — SIP digest authentication data IP_AUTHENTICATION SIP digest authentication data typedef struct { unsigned short version; char* realm; char* identity; char* username; char* password; } IP_AUTHENTICATION; Description The IP_AUTHENTICATION data structure is used when setting or removing SIP authentication quadruplets.
PAGE 543
basic capability information — IP_CAPABILITY IP_CAPABILITY basic capability information typedef struct { int int int int IP_CAPABILITY_UNION char } IP_CAPABILITY; capability; type; direction; payload_type; extra; rfu[0x10]; Description The IP_CAPABILITY data structure provides basic media capability information, including the capability or codec identification and the direction.
PAGE 544
IP_CAPABILITY — basic capability information direction Identifies the direction and state of the stream that the media attributes in this structure apply to. Possible values are: • IP_CAP_DIR_LCLRECEIVE – Capabilities specified in the structure refer to receive direction of a full duplex media session. • IP_CAP_DIR_LCLRECVONLY – Capabilities refer to a half-duplex, receive-only media session. • IP_CAP_DIR_LCLSENDONLY – Capabilities refer to a half-duplex, send-only media session.
PAGE 545
parameters for different capability categories — IP_CAPABILITY_UNION IP_CAPABILITY_UNION parameters for different capability categories typedef union { IP_AUDIO_CAPABILITY IP_VIDEO_CAPABILITY IP_DATA_CAPABILITY } IP_CAPABILITY_UNION; audio; video; data; Description The IP_CAPABILITY_UNION union enables different capability categories to define their own additional parameters or interest.
PAGE 546
IP_CONNECT — associate a Media device with a T.38 Fax device IP_CONNECT associate a Media device with a T.38 Fax device typedef struct { unsigned short int int eIPConnectType_e } IP_CONNECT; version; mediaHandle; faxHandle; connectType; Description The IP_CONNECT data structure contains information required when associating a Media device with a T.38 Fax device required when switching from an audio coder to a T.38 coder and vice versa.
PAGE 547
DTMF information — IP_DTMF_DIGITS IP_DTMF_DIGITS DTMF information typedef struct { char digit_buf[IP_MAX_DTMF_DIGITS]; unsigned int num_digits; } IP_DTMF_DIGITS; Description The IP_DTMF_DIGITS data structure is used to provide DTMF information when the digits are received in a User Input Indication (UII) message with alphanumeric data.
PAGE 548
IP_DATA_CAPABILITY — basic data capability information IP_DATA_CAPABILITY basic data capability information typedef struct { int max_bit_rate; } IP_DATA_CAPABILITY; Description The IP_DATA_CAPABILITY data structure provides additional information about the data capability. Field Descriptions The fields of the IP_DATA_CAPABILITY data structure are described as follows: max_bit_rate Possible values are: • 2400 • 4800 • 9600 • 14400 The recommended value for T.38 coders is 14400.
PAGE 549
H.221 nonstandard data — IP_H221NONSTANDARD IP_H221NONSTANDARD H.221 nonstandard data typedef struct { int country_code; int extension; int manufacturer_code; } IP_H221NONSTANDARD; Description The IP_H221NONSTANDARD data structure is used to store H.221 data associated with H.323 nonstandard data. Field Descriptions The fields of the IP_H221NONSTANDARD data structure are described as follows: country_code The country code. Range: 0 to 255; any value x>255 is treated as x%256.
PAGE 550
IP_REGISTER_ADDRESS — gatekeeper registration information IP_REGISTER_ADDRESS gatekeeper registration information typedef struct { char reg_client [IP_REG_CLIENT_ADDR_LENGTH]; char reg_server [IP_REG_SERVER_ADDR_LENGTH]; int time_to_live; int max_hops; } IP_REGISTER_ADDRESS; Description The IP_REGISTER_ADDRESS data structure is used to store registration information.
PAGE 551
TSM protocol alternate ID — IP_TUNNELPROTOCOL_ALTID IP_TUNNELPROTOCOL_ALTID TSM protocol alternate ID typedef struct { unsigned long version; char protocolType[MAX_TSM_ALTID_VARS_LENGTH]; int protocolTypeLength; char protocolVariant[MAX_TSM_ALTID_VARS_LENGTH]; int protocolVariantLength; char subIdentifier[MAX_TSM_ALTID_VARS_LENGTH]; int subIdentifierLength; } IP_TUNNELPROTOCOL_ALTID; Description The IP_TUNNELPROTOCOL_ALTID data structure is used in H.
PAGE 552
IP_TUNNELPROTOCOL_OBJECTID — tunneled signaling protocol object ID IP_TUNNELPROTOCOL_OBJECTID tunneled signaling protocol object ID typedef struct { unsigned long version; char TunneledProtocol_Oid[MAX_TSM_OBJID_VARS_LENGTH]; int TunneledProtocol_OidLength; char subIdentifier[MAX_TSM_OBJID_VARS_LENGTH]; int subIdentifierLength; } IP_TUNNELPROTOCOL_OBJECTID; Description The IP_TUNNELPROTOCOL_OBJECTID data structure is used in H.
PAGE 553
information about an IPT board device — IP_VIRTBOARD IP_VIRTBOARD information about an IPT board device typedef struct { unsigned short unsigned int unsigned int unsigned int IP_ADDR unsigned short unsigned short void unsigned short unsigned int unsigned int unsigned int MIME_MEM unsigned short IP_ADDR unsigned short char * EnumSIP_Enabled EnumSIP_TransportProtocol EnumSIP_Persistence unsigned short EnumSIP_TransportProtocol EnumSIP_RequestRetry EnumSIP_Enabled unsigned int SIP_TLS_ENGINE }IP_VIRTBOARD; v
PAGE 554
IP_VIRTBOARD — information about an IPT board device h323_max_calls The maximum number of IPT devices that can be used for H.323 calls. Valid values are in the range from IP_CFG_NO_CALLS (=0) to IP_CFG_MAX_AVAILABLE_CALLS (=2016). The default value is 120. This field must not be set to IP_CFG_NO_CALLS if sip_max_calls is also set to that value. When the library is being started in 3PCC operating mode, this field should be set to IP_CFG_NO_CALLS (=0).
PAGE 555
information about an IPT board device — IP_VIRTBOARD • IP_H323_RETRIEVE_UUIE_ENABLE – Enable receiving User-to-User Information Elements from incoming H.323 messages sip_mime_mem (structure version ≥ 0x104 only) Sets the number and size of buffers that will be allocated for the MIME memory pool when the SIP MIME feature is enabled (no buffers are allocated if the feature is not enabled).
PAGE 556
IP_VIRTBOARD — information about an IPT board device • ENUM_TCP – use TCP protocol for the outbound proxy; if this value is set when TCP is not enabled or when TCP is enabled but no SIP proxy is configured, gc_Start( ) returns an IPERR_BAD_PARM error • ENUM_TLS – use TLS for the outbound proxy; if this value is set when either TCP or TLS is not enabled (TLS operates on top of TCP), gc_Start( ) returns an IPERR_BAD_PARM error • ENUM_UDP (default) – use UDP protocol for the outbound proxy E_SIP_Persistence
PAGE 557
information about an IPT board device — IP_VIRTBOARD E_SIP_OPTIONS_Access (structure version ≥ 0x108 only) Enables application access to incoming OPTIONS, and the ability to send OPTIONS requests. The following symbolic values are defined: • ENUM_Disabled (default) – disable application access to OPTIONS messages • ENUM_Enabled – enable application access to OPTIONS messages sip_registrar_registrations (structure version ≥ 0x109 only) Specifies the number of unique SIP registrations that can be created.
PAGE 558
IPCCLIB_START_DATA — IP call control library configuration information IPCCLIB_START_DATA IP call control library configuration information typedef struct { unsigned short unsigned char unsigned char IP_VIRTBOARD unsigned long unsigned short } IPCCLIB_START_DATA; version; delimiter; num_boards; *board_list; max_parm_data_size; media_operational_mode; Description The IPCCLIB_START_DATA structure is used to configure the IP call control library when starting Dialogic® Global Call API.
PAGE 559
IP call control library configuration information — IPCCLIB_START_DATA • IPSET_TUNNELEDSIGNALMSG / IPPARM_TUNNELEDSIGNALMSG_DATA Note: When using H.323, the stack limits the total size of messages to the value of this field + 512 bytes. Because of the presence of other payload in the message, it may not be possible to use the maximum parameter data size defined in this field for H.323 Nonstandard Data or Annex M Tunneled Signaling Message data. If the total size of an H.
PAGE 560
REQUEST_ERROR — SIP request retry info REQUEST_ERROR SIP request retry info typedef struct { unsigned short version; unsigned int error; char method[IP_SIP_METHODSIZE] }REQUEST_ERROR, *REQUEST_ERRORP; Description The REQUEST_ERROR structure is used to contain information about the conditions that exist when the transmission of a SIP request fails.
PAGE 561
RTP address — RTP_ADDR RTP_ADDR RTP address typedef struct { int version unsigned short port; unsigned char ip_ver; union { unsigned int ipv4; unsigned int ipv6[4]; } u_ipaddr; } RTP_ADDR, *RTP_ADDRP; Description The RTP_ADDR data structure contains a complete RTP address, which includes both the port number and the IP address. The RTP_ADDR structure is used when retrieving the local and remote RTP addresses from the Global Call completion event when a call is connected.
PAGE 562
SIP_TLS_ENGINE — TLS engine configuration information SIP_TLS_ENGINE TLS engine configuration information typedef struct { unsigned long unsigned short EnumSIP_TLS_METHOD char * char * char * char * char * char * unsigned int char ** unsigned int char ** unsigned int char ** char * char * char * char * EnumSIP_Enabled EnumSIP_Enabled EnumSIP_Enabled } SIP_TLS_ENGINE; version; /* system use only */ sip_tls_port; E_sip_tls_method; local_rsa_private_key_filename; local_rsa_private_key_password; local_rsa_cer
PAGE 563
TLS engine configuration information — SIP_TLS_ENGINE • ENUM_TLS_METHOD_TLS_V1 – use TLS ver. 1 (Default value) local_rsa_private_key_filename name of file containing TLS RSA private key of local certificate. File must be PEM (base64 encoded) X509 format, in plain text or encrypted. Default is NULL. local_rsa_private_key_password password string used to read TLS RSA private key of local certificate if it is encrypted.
PAGE 564
SIP_TLS_ENGINE — TLS engine configuration information crl_number number of optional certificate revocation list (CRL) files. An engine may look up CRLs while examining the incoming certificates. To add one or more CRL files, use this field to specify the number of files in the crl_filename array. Default value is 0. crl_filename array of filenames for optional certificate revocation lists (CRLs). Files must be PEM format in plain text. The size of the array is specified by crl_number. Default is NULL.
PAGE 565
IP-Specific Event Cause Codes 11. 11 This chapter lists the IP-specific error and event cause codes and provides a description of each code. The codes described in this chapter are defined in the gcip_defs.h header file. When a GCEV_DISCONNECTED event is received, use the gc_ResultInfo( ) function to retrieve the reason or cause of that event. When using gc_DropCall( ) with H.323, only event cause codes prefixed by IPEC_H2250 or IPEC_Q931 should be specified in the cause parameter.
PAGE 566
IP-Specific Event Cause Codes IPERR_COPYING_OCTET_STRING Unable to copy octet string. IPERR_COPYING_OR_RESOLVING_ALIAS An error occurred while copying the alias. The error could be the result of a memory allocation failure or it could be an invalid alias format. IPERR_DESTINATION_UNKNOWN Failure to locate the host with the address given. IPERR_DIAL_ADDR_MUST_BE_ALIAS The address being dialed in this case may not be an IP address or domain name.
PAGE 567
IP-Specific Event Cause Codes IPERR_INVALID_ID An invalid ID was specified. IPERR_INVALID_IP_ADDRESS The IP address given is invalid. IPERR_INVALID_MEDIA_HANDLE The specified media handle is different from the already attached media handle. IPERR_INVALID_PHONE_NUMBER The phone number given is invalid. IPERR_INVALID_PROPERTY The property ID is invalid. IPERR_INVALID_STATE Invalid state to make this call. IPERR_INVALID_URL_ADDRESS The URL address given is invalid. IPERR_INVDEVNAME Invalid device name.
PAGE 568
IP-Specific Event Cause Codes IPERR_NOANSWER Timeout due to no answer from peer. IPERR_NOT_IMPLEMENTED The function or property call has not been implemented. This differs from IPERR_UNSUPPORTED in that there is the implication that this is an early release which intends to implement the feature or function.
PAGE 569
IP-Specific Event Cause Codes IPERR_UNKNOWN_API_GUID This is the result of either passing in a bogus GUID or one that is not found in the current DLL or executable. IPERR_UNRESOLVABLE_DEST_ADDRESS No Gateway, Gatekeeper, or Proxy is specified, therefore the destination address must be a valid resolvable address. In the case of IP based call control, the address specified should be an IP address or a resolvable host or domain name.
PAGE 570
IP-Specific Event Cause Codes IPEC_CHAN_REJECT_separateStackEstablishmentFailed A request to run the data portion of a call on a separate stack failed. IPEC_CHAN_REJECT_invalidSessionID Attempt by the slave to set the SessionID when opening a logical channel to the master. IPEC_CHAN_REJECT_masterSlaveConflict Attempt by the slave to open logical channel in which the master has determined a conflict may occur.
PAGE 571
IP-Specific Event Cause Codes IPEC_INFO_SOME_TIMEOUT Only some digits are available; timed out. IPEC_NO_MATCHING_CAPABILITIES No intersection was found between the proposed and matching capabilities. IPEC_REG_FAIL_duplicateAlias The alias used to register with the Registration and Admission server is already registered. This failure typically results if the endpoint is already registered. It could also occur with some servers if a registration is attempted too soon after unregistering using the same alias.
PAGE 572
IP-Specific Event Cause Codes IPEC_MEDIA_RxFailed Attempt to establish or terminate an Rx channel with attached capabilities failed. The application is expected to keep the Tx capabilities unchanged in the next call to gc_AttachEx( ). IPEC_MEDIA_TxRxFailed Attempts to establish or terminate Tx and Rx channels with attached capabilities failed. IPEC_MEDIA_OnlyTxFailed Attempts to establish a Tx channel with attached capabilities failed. The status of other media channel is unavailable.
PAGE 573
IP-Specific Event Cause Codes IPEC_FAIL_TxRx_unspecified Both the Tx and Rx channels failed to open for unspecified reasons. IPEC_FAIL_TxUnspecifiedRxTimeout A Tx channel failed to open for unspecified reasons and the Rx channel failed to open because of a timeout. IPEC_FAILTxUnspecifiedRxResourceUnsuff A Tx channel failed to open for unspecified reasons and the Rx channel failed to open because of insufficient resources.
PAGE 574
IP-Specific Event Cause Codes 11.3 Internal Disconnect Reasons The following internal disconnect reasons are supported when using H.
PAGE 575
IP-Specific Event Cause Codes IPEC_InternalReasonRemoteTermination (0x3fb, 1019 decimal) Cause 19; Remote termination IPEC_InternalReasonRejection (0x3fc, 1020 decimal) Cause 20; Call rejected IPEC_InternalReasonSIT (0x3fd, 1021 decimal) Cause 21; Special Information Tone (SIT) IPEC_InternalReasonSITCustIrreg (0x3fe, 1022 decimal) Cause 22; SIT, Custom Irregular IPEC_InternalReasonSITNoCircuit (0x3ff, 1023 decimal) Cause 23; SIT, No Circuit IPEC_InternalReasonSITReorder (0x400, 1024 decimal) Cause 24; SIT,
PAGE 576
IP-Specific Event Cause Codes IPEC_InternalReasonFacilityNotImplemented (0x40f, 1039 decimal) Cause 39; Facility not implemented IPEC_InternalReasonServiceNotImplemented (0x410, 1040 decimal) Cause 40; Service not implemented IPEC_InternalReasonBarredInbound (0x411, 1041 decimal) Cause 41; Barred inbound calls IPEC_InternalReasonBarredOutbound (0x412, 1042 decimal) Cause 42; Barred outbound calls IPEC_InternalReasonDestIncompatible (0x413, 1043 decimal) Cause 43; Destination incompatible IPEC_InternalReaso
PAGE 577
IP-Specific Event Cause Codes IPEC_H2250ReasonUnreachableGatekeeper (0x7d6, 2006 decimal) Maps to Q.931/Q.850 cause 38 - Network out of order; indicates that the network is not functioning correctly and that the condition is likely to last a relatively long period of time, for example, immediately re-attempting the call is not likely to be successful. IPEC_H2250ReasonGatewayResource (0x7d7, 2007 decimal) Maps to Q.931/Q.
PAGE 578
IP-Specific Event Cause Codes recognize the transit network either because the transit network does not exist or because that particular transit network, while it does exist, does not serve the equipment which is sending this cause. This cause is supported on a network-dependent basis. IPEC_Q931Cause03NoRouteToDestination (0xbbb, 3003 decimal) Q.
PAGE 579
IP-Specific Event Cause Codes IPEC_Q931Cause26NonSelectUserClearing (0xbd2, 3026 decimal) Q.931 cause 26 - Non-selected user clearing; indicates that the user has not been awarded the incoming call. IPEC_Q931Cause27DestinationOutOfOrder (0xbd3, 3027 decimal) Q.931 cause 27 - Destination out of order; indicates that the destination indicated by the user cannot be reached because the interface to the destination is not functioning correctly.
PAGE 580
IP-Specific Event Cause Codes IPEC_Q931Cause44RequestedCircuitChannelNotAvailable (0xbe4, 3044 decimal) Q.931 cause 44 - Requested circuit/channel not available; returned when the circuit or channel indicated by the requesting entity cannot be provided by the other side of the interface. IPEC_Q931Cause47ResourceUnavailableUnspecified (0xbe7, 3047 decimal) Q.
PAGE 581
IP-Specific Event Cause Codes 1 to 12 and the user equipment or the network attempts to use channels 13 through 23, this cause is generated. IPEC_Q931Cause83AsuspendedCallExistsButThisCallIdentityDoesNot (0xc0b, 3083 decimal) Q.931 cause 83 - A suspended call exists, but this call identity does not; indicates that a call resume has been attempted with a call identity that differs from that in use for any presently suspended call(s). IPEC_Q931Cause84CallIdentityInUse (0xc0c, 3084 decimal) Q.
PAGE 582
IP-Specific Event Cause Codes IPEC_Q931Cause101MessageNotCompatibleWithCallState (0xc1d, 3101 decimal) Q.931 cause 101 - Message not compatible with call state; indicates that a message that is incompatible with the call state has been received. IPEC_Q931Cause102RecoveryOnTimeExpiry (0xc1e, 3102 decimal) Q.931 cause 102 - Recovery on timer expiry; indicates that a procedure has been initiated by the expiry of a timer in association with error handling procedures.
PAGE 583
IP-Specific Event Cause Codes IPEC_RASReasonDuplicateAlias (0xfad, 4013 decimal) The alias is registered to another endpoint. (In RRJ messages.) IPEC_RASReasonTransportNotSupported (0xfae, 4014 decimal) One or more of the transport addresses are not supported. (In RRJ messages.) IPEC_RASReasonCallInProgress (0xfaf, 4015 decimal) A call is already in progress. (In URJ messages.) IPEC_RASReasonRouteCallToGatekeeper (0xfb0, 4016 decimal) The call has been routed to a gatekeeper. (In ARJ messages.
PAGE 584
IP-Specific Event Cause Codes IPEC_RASFullRegistrationRequired (0xfc0, 4032 decimal) Registration permission has expired. (In RRJ messages.) IPEC_RASRouteCallToSCN (0xfc1, 4033 decimal) The call was routed to a switched circuit network. (In ARJ and LRJ messages.) IPEC_RASAliasesInconsistent (0xfc2, 4034 decimal) Multiple aliases in the request identify separate people. (In ARJ and LRJ messages.) 11.5 Failure Response Codes When Using SIP The following failure response codes apply when using SIP.
PAGE 585
IP-Specific Event Cause Codes This status code can be used for applications where access to the communication channel (for example, a telephony gateway) rather than the callee, requires authentication. IPEC_SIPReasonStatus408RequestTimeout (0x1520, 5408 decimal) SIP Request Failure Response 408 - Request Timeout - The server could not produce a response within a suitable amount of time, for example, if it could not determine the location of the user in time.
PAGE 586
IP-Specific Event Cause Codes IPEC_SIPReasonStatus480TemporarilyUnavailable (0x1568, 5480 decimal) SIP Request Failure Response 480 - Temporarily Unavailable - The callee's end system was contacted successfully but the callee is currently unavailable (for example, is not logged in, logged in but in a state that precludes communication with the callee, or has activated the “do not disturb” feature). The response may indicate a better time to call in the Retry-After header field.
PAGE 587
IP-Specific Event Cause Codes description of media capabilities may be present in the response, which is formatted according to the Accept header field in the INVITE (or application/SDP if not present), the same as a message body in a 200 (OK) response to an OPTIONS request. IPEC_SIPReasonStatus491RequestPending (0x1573, 5491 decimal) SIP Request Failure Response 491 - Request Pending - The request was received by a User Agent Server (UAS) that had a pending request within the same dialog.
PAGE 588
IP-Specific Event Cause Codes IPEC_SIPReasonStatus505VersionNotSupported (0x1581, 5505 decimal) Server Failure Response 505 - Version Not Supported - The server does not support, or refuses to support, the SIP protocol version that was used in the request. The server is indicating that it is unable or unwilling to complete the request using the same major version as the client, other than with this error message.
PAGE 589
IP-Specific Event Cause Codes IPEC_SIPReasonStatusCANCEL (0x16a9, 5801 decimal) SIP reason status 801. CANCEL code. SIP Message Error Codes IPEC_MIME_BUFF_TOO_SMALL MIME buffer size is smaller than the incoming MIME part in a SIP message. IPEC_MIME_POOL_EMPTY MIME memory pool is exhausted. IPEC_SipHeaderTruncation A SIP header field exceeded the configured maximum parameter length and was truncated.
PAGE 590
IP-Specific Event Cause Codes 590 Dialogic® Global Call IP Technology Guide — November 2007 Dialogic Corporation
PAGE 591
Supplementary Reference Information 12. 12 This chapter lists related publications and includes other reference information as follows: • References to More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591 • SIP Transaction Timer Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592 • DNS Configuration for SIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PAGE 592
Supplementary Reference Information 12.2 SIP Transaction Timer Values This section provides information on the various timers that affect Global Call’s behavior when handling SIP transactions. The duration values for these timers are preconfigured and are not configurable by applications. retransmissionT1 T1 determines several timers as defined in RFC3261.
PAGE 593
Supplementary Reference Information cancelInviteNoResponseTimer When sending a CANCEL request on an Invite request, the User Agent waits cancelInviteNoResponseTimer milliseconds before timeout termination if there is no response for the cancelled transaction.
PAGE 594
Supplementary Reference Information 12.4 Called and Calling Party Address List Format When Using H.
PAGE 595
Supplementary Reference Information – Party Number Type ::= (select either the numerical or string value from the following list): • 0.PUU - The numbering plan follows the E.163 and E.164Recommendations. • PUI - The number digits carry a prefix indicating type of number according to national recommendations. • PUN - The number digits carry a prefix indicating the type of number according to • • • • • • • • • national recommendations.
PAGE 596
Supplementary Reference Information Examples of Called and Calling Party Addresses Some examples of called party and calling party addresses are: • Called and Calling Party addresses: 1111;1111 • NAME: John, NAME: Jo • TA:192.114.36.
PAGE 597
Glossary alias: A nickname for a domain or host computer on the Internet. blind transfer: See unsupervised transfer. call transfer: See supervised transfer and unsupervised transfer. codec: A device that converts analog voice signals to a digital form and vice versa. In this context, analog signals are converted into the payload of UDP packets for transmission over the internet. The codec also performs compression and decompression on a voice stream. H.225.
PAGE 598
Q.931: The Q.931 protocol defines how each H.323 layer interacts with peer layers, so that participants can interoperate with agreed upon formats. The Q.931 protocol resides within H.225.0. As part of H.323 call control, Q.931 is a link layer protocol for establishing connections and framing data. RTP: Real-time Transport Protocol.
PAGE 599
Index Numerics 180 Ringing sending 444 183 Session Progress sending 444 A Alarm Source Object (ASO) 264 B Bearer Capability IE 122 busy reason codes, setting 132 conference goal 122 options 462 retrieving 143 set ID and parameter ID for 514 conference ID retrieving 143 set ID and parameter ID for 515 connection method 122 setting fast start 116 setting slow start 116 types of 115 connection methods set ID and parameter ID for 512 Contact Display string 178, 184 Contact URI 178, 184 current call parameter
PAGE 600
DTMF configuration 238 detection notification 240 generating 241 modes 239 supported type bitmap 122 using a voice resource to generate or detect 241 E early media fast start and slow start setup modes 115 events, enabling and disabling 122 F Facility IE 122 retrieving 143 Facility messages (Q.931), sending 244 fast start 115 H.
PAGE 601
GCSET 461, 464 H H.221 nonstandard data set ID and parameter ID for 534, 536 H.221 nonstandard data, set ID and parameter ID for 526 H.221 nonstandard information, retrieving 144 H.225.0, purpose of 31 H.245 channel 117 H.245 messages sending nonstandard UUI 242 H.245 User Input Indication 238 H.245, purpose of 31 H.323 basic call scenario 32 busy code, setting 133 call scenario via a gateway 36 protocol stack 31 specification 29 terminals 30 types of entities 30 H.323 fast start 117 H.
PAGE 602
nonstandard registration messages (H.221), sending 245 nonstandard UII messages (H.245), sending 243 O Object Identifiers (OIDs) 332 OIDs (Object Identifiers) 332 optional H.
PAGE 603
SIP informational response message sending 444 SIP message header fields setting and retrieving 172 SIP Message Information fields 123 SIP MIME 188 enabling 191 SIP OK (200) message 263 SIP REGISTER 269 SIP Ringing (180) message 263 SIP-T 188 slow start 115 slow start, H.323 116 V vendor information 124 H.221 nonstandard data 542, 549 product ID 536 received from a peer 143 version ID 536 vendor product ID, retrieving 144 Vendor Version ID 144 version ID, setting 536 VoIP, definition of 29 T T.
PAGE 604
Dialogic® Global Call IP Technology Guide — November 2007 Dialogic Corporation