The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
This chapter describes the Cisco Unified Communications Gateway Services Application Programming Interface (CUCGSAPI). The CUCGSAPI enables the development of advanced Cisco Unified Communication applications and services on the platforms running Cisco IOS and Cisco IOS XE software by providing an interface to the Cisco Unified Communications Gateway Services.
CUCGSAPI provides the developer with access to the following unified communications gateway services:
CUCGSAPI allows you to develop an application that interacts with the Cisco Unified Communications Gateway Services on voice gateways. The application accesses the Cisco Unified Communications Gateway Services via SOAP messages.
You can configure secure and nonsecure modes of connectivity between Cisco Unified Communications Gateway Services and application. Nonsecure mode uses HTTP protocol and secure mode uses HTTPS protocol.
Figure 1-1 illustrates the Cisco Unified Communications Gateway Services interface in nonsecure mode. In nonsecure mode, Cisco supports the extended call control (XCC) provider, extended call detail record (XCDR) provider, extended serviceability (XSVC) provider, and extended media forking (XMF).
Figure 1-1 Cisco Unified Communications Gateway Services Interface in nonsecure mode
Figure 1-2 illustrates the Cisco Unified Communications Gateway Services interface in secure mode. In secure mode, Cisco supports the extended call control (XCC) provider, and extended serviceability (XSVC) provider.
Figure 1-2 Cisco Unified Communications Gateway Services Interface in secure mode
Web service is a standards-based framework that allow applications operating on different platforms to interact over the Internet. Cisco Unified Communications Gateway Services, like web services, are platform independent and language neutral. With CUCGSAPI, you can develop your application in the language and operating system of your choice and communicate directly with the Cisco Unified Communications Gateway Services running on the voice gateway.
The Cisco Unified Communications Gateway Services API supports the following standards and protocol:
Table 1-1 lists the differences in behavior between nonsecure and secure mode.
|
|
|
---|---|---|
Cisco IOS software based platforms and Cisco IOS XE software based platforms |
||
The providers on the voice gateway provide services on the voice gateway for remote applications. Cisco Unified Communications Gateway Services API enables applications to interact with the providers and is comprised of the following provider objects:
Each provider has a unique URL identifier and communicates with the application via SOAP messages. The providers can be in one of two states:
Figure 1-3 illustrates the relationship between the IOS components.
Figure 1-3 Cisco Unified Communications Gateway Services Components
When a provider is configured and enabled on the voice gateway, it performs the following functions:
CUCGSAPI uses the WSDL specification to define the services that are available on the voice gateway. These services are represented as providers on the voice gateway.
Table 1-2 lists the namespace for the Cisco Unified Communications Gateway Services
|
|
---|---|
Table 1-3 lists the URL and inbound location that the application uses to communicate with the server in nonsecure mode.
|
|
---|---|
http://<access_router>:8090/cisco_xcc 1 |
|
1.The access_router is the hostname or IP address of the router that with Cisco Unified Communications Gateway Services. Table 1-4 lists the URL and inbound location that applications uses to communicate with the server in secure mode. |
|
|
---|---|
Before an application can register with the voice gateway, you must first configure the application’s service URL on the voice gateway. The URL is used to authenticate messages from the application. When the voice gateway first boots up, the provider sends status messages to the applications that are in its configuration. The voice gateway sends status messages when the provider changes its status.
The application initiates registration by sending a registration message to the appropriate provider. The provider generates a unique registration ID and sends it back to the application. The unique registration ID identifies the registered session and is used in all messages that are sent during the registered session.
The state of the registered session and the status of the messages that are sent between the provider and application have one of the following value:
– When the application unregisters with the provider.
– When an application fails to respond to probing messages.
– When the administrator shuts down the provider service on the voice gateway.
The XCC provider gives an application the capability to control all the legs of a standard call. With the XCC provider, the application can perform auxiliary call control and can control some network elements.
The XCC provider has the following characteristics:
Figure 1-4 illustrates the XCC call control abstraction.
When an application registers with the XCC provider, the application configures event filter parameters that the application is interested in monitoring, and the XCC provider installs a connection listener to monitor the calls. XCC notifies the application when a call or connection event matches the event filters that were configured. When the application updates event filter parameters, the updates only apply to new calls, not existing calls.
The XCC provider API is described in XCC Provider Operations.
The XCC call APIs describe the endpoints and trunks that are associated with a call. The APIs in XCC call API, and the associated XCC connection describes the control and media flow in a call. The provider notifies the application when there is a change to the state of a call and sends update information on the call, address, and connections.
A call abstraction is represented in Figure 1-5 on the voice gateway in one of the following three states:
Figure 1-5 Call Abstraction Model
External applications can enable the voice gateway to detect changes to the call media set attributes on a call and have the voice gateway send a notify event message. Table 1-5 lists the call media set attributes that the gateway can detect.
|
|
---|---|
Enables the voice gateway to detect when a call changes between the following call modes: Note ISDN calls with an unrestricted bearer capability value are reported as data calls. |
|
Enables the voice gateway to detect a DTMF digit in the media stream or a DTMF relay. Note The notify event message includes the timestamp if the DTMF event is detected in IOS. Note For notify event messages, the application should use the voice gateway as the NTP2 server for synchronizing clocks. |
|
Enables the voice gateway to detect when the media activity state changes from “Active” to “Inactive” or vice versa. |
|
Enables the voice gateway to detect the following specified tones: Note Tone detection is not supported for a FXO voice port if the supervisory tone detection feature is enabled. |
|
Enables media forking on a connected call to target a RTP address. For more information on media forking, see the “XCC Call Media Forking” section. |
|
Note XCC Call Media Forking is not supported in secure mode.
External applications can request media forking for a call. When the application requests media forking, it must provide the XCC provider with two unique remote RTP ports (nearEndAddr and farEndAddr). The XCC provider identifies the incoming connection of a call, forks both the transmit (TX) and receive (RX) packets, and sends the packets to the targeted RTP ports. The XCC provider uses the nearEndAddr element for the forked TX media stream and the farEndAddr XCC element to record the RX media stream. The two forked media streams are sent from the voice gateway in a “SEND ONLY” direction.
Media forking has the following limitations:
The XCC provider updates the application on the status of the media forking by including one of the following states in the NotifyXccCallData message.
The XCC connection describes the relationship in a XCC call and the endpoint or trunk in the call. Figure 1-6 illustrates the connection states.
Table 1-6 describes the connection states and the activity and exchanges that can occur between the voice gateway and application when the application sets up event notifications for a particular connection state.
The extended serviceability provider (XSVC provider) monitors the health of the trunk and provides the application with real-time trunk status.
The XSVC provider can monitor both traditional public switched telephone network (PSTN) trunks and VoIP trunks. You must configure the XSVC provider and install a route listener for XSVC on the interested trunk group to begin monitoring the trunk status. The route listener communicates with the trunk group resource manager to obtain information on the trunks, including alarm information for T1/E1 trunks.
For PSTN trunks, the trunk group is a logical grouping of interfaces with the same signaling characteristics, such as DS1, FXO, or PRI interfaces. The trunk group can have more than one PRI interface and can also support FXO, but you cannot mix FXO and T1/E1 interfaces. The trunk group resource manager supports the logical configuration of trunk groups.
For VoIP trunks, the trunk manager monitors a VoIP trunks by using Internet Control Message Protocol (ICMP) pings. The trunk manager supports up to 1000 trunks.
When the application registers with the XSVC provider, the application obtains a handler that the application uses to receive snapshot information on all the routes or specific routes. The XSVC provider can support up to 8 different applications, with each application able to monitor a particular group of trunks.
Figure 1-7 illustrates the relationship between the application, XSVC route, and XSVC provider.
The XSVC provider has the following characteristics:
When the application registers with the XSVC provider, a route listener is installed on the trunk interfaces. If filters are not specified in the registration message, the XSVC provider does not filter out any events. For the application to receive the most current trunk configuration, we recommend that you do not filter out the ROUTE_CONF_UPDATED event.
The XSVC provider API is described in Xsvc Provider Operations.
With the route snapshot API, the application can request and receive a summary from the voice gateway on all the routes that are currently being monitored in a compact format. The application can also set up a filter to listen to specific routes. The application can also request that the XSVC provider send detail information for a specific route. For T1/E1 trunks, the XSVC provider sends additional information, such as channels, total available channels, alarm, and error statistics.
Table 1-7 describes the alarm definition that can be found in XSVC route messages.
|
|
---|---|
Far end LOF3 indication (a.k.a. Yellow Alarm) |
|
Far end sending AIS4 |
|
Far end is sending TS16 LOMF5 |
|
|
Table 1-7 defines the statistics that are collected and can be found in XSVC route messages.
|
|
---|---|
The XCDR provider sends information on a call detail record (CDR) to the registered application when a call ends. The CDR contains statistics on the call and calling party and called party information in a CSV format. The XCDR provider can support up to eight remote application.
When the application registers with the XCDR provider, it obtains a handler that the application can use to receive CDR records. The application can choose to receive either the compact or detailed CDR format.
Note By default, the XCDR provider sends out the CDR record in a compact format to save bandwidth.
Figure 1-8 illustrates the relationship between the application, CDR, and XCDR provider.
The XCDR provider API is described in Xcdr Provider Operations.
XCDR CDR is responsible for collecting CDR information and generating events that are sent to the application. The application can specify whether it wants the CDR record in compact or detailed format by using the RequestXcdrSetAttribute message.
For detail information on the name and order of the call detail record fields, see CDR Accounting for Cisco IOS Voice Gateways .
XMF provider gives an application the capability to monitor calls and trigger media forking on the calls and has the capability to service up to 32 applications. The XMF provider can invoke a call-based or a connection-based media forking using the Unified Communications (UC) API. After the media forking is invoked, it can preserve the media forking initiated by the web application if the WAN connection to the application is lost. The XMF provider also provides the recording tone to the parties involved in the call.
The XMF provider API is described in Xmf Provider Operations.
In call-based media forking of the gateway, the stream from the calling party is termed as near-end stream and the stream from the called party is termed as far-end stream. The XMF provider actively handles single media forking request per session. Any new media forking request from the external application will override or stop the current forking instance and would start a new forking instance (to the appropriate target IP address or ports). After the media forking request is accepted, the XMF provider returns a response message and starts to fork media streams of a connection to the target forked streams. A NotifyXmfCallData message will be notified to the application for the updated media forking status, that is, FORK-FAILED, FORK_STARTED, or FORK_DONE.
In connection-based media forking of the gateway, the incoming stream to the connection is termed as near-end stream and the outgoing stream of the connection is termed as far-end stream. The XMF provider actively handles single media forking request per session. Any new media forking request from the external application will override or stop the current forking instance and would start a new forking instance (to the appropriate target IP address or ports). After the media forking request is accepted, the XMF provider returns a response message and starts to fork media streams of a connection to the target forked streams.
Figure 1-9 XMF Connection Based Media Forking
A NotifyXmfConnectionData message will be notified to the application for the updated media forking status:
The XMF connection describes the relationship between an XMF call and the endpoint (or trunk) involved in the call. A connection abstraction maintained in the gateway has the following connection states:
SRTP forking is supported in XMF and XCC application service providers and the supported APIs are RequestCallMediaForking, RequestCallMediaSetAttributes, and RequestConnectionMediaForking.
SRTP forking is supported for SRTP-to-SRTP, SRTP-to-RTP, and RTP-to-SRTP calls.
SRTP Crypto keys are notified over the API.
Supports automatic stopping of media forking when stream changes from SRTP or to SRTP.
For SRTP forking, the optional Crypto tag in NotifyXmfConnectionData or NotifyXmfCallData message indicates the context of an actively forked SRTP connection.
Note The Crypto tag is only present in the notification message where FORK_STARTED tag is present.
The optional Crypto tag specifies the following:
Crypto suite can be one of the two suites supported in IOS:
The following is a sample SDP data sent in an SRTP call:
|
|
---|---|
o=CiscoSystemsSIP-GW-UserAgent 7826 3751 IN IP4 172.18.193.98 |
o=CiscoSystemsSIP-GW-UserAgent 7826 3751 IN IP4 172.18.193.98 |
Note The application is notified of the content in Crypto and inline SDP lines.
Multiple XMF allows multiple (maximum 32) web applications to register with the XMF provider as separate XMF applications and provide redundancy for the voice calls recording. Recording tone provides recording tone capability to the recording sessions. Recording tone is supported for IP to IP, IP to TDM, and TDM to TDM trunks.
An example topology is as shown below where 4 CUCM applications are deployed. CUCM triggers media forking request to voice gateway. Recording tone is played to the parties involved in the call based on the recordTone parameter set in the media forking request.
Figure 1-10 Multiple XMF Applications and Recording Tone
Media forking can be invoked using any of the following APIs:
The “recordTone” parameter can be enabled in any of the above requests and recording tone will be played for the parties involved in the call. The “recordTone” parameter in the API request can have the following values:
There is no difference in the recording tone beep when any country value is chosen. Recording tone beep is played at an interval of every 15 seconds. Digital signal processors and other resources are not utilized for playing recording tone even for transcoded calls. No specific configuration is required to enable or disable recording tone. By default, no recording tone is enabled.
If “recordTone” parameter is enabled only on the farEndAddr, then this tone is played only on the outgoing leg. Likewise, if enabled only on the nearEndAddr, then the tone is played only on the incoming leg. When enabled in both the far and near end, then recording tone is played on both the legs.
The RequestXmfConnectionMediaForking API allows insertion of recording tone on a per connection basis. There could be scenarios where one leg receives two recordTone insertion requests. When a leg receives recordTone insertion request, the nearEnd request always takes precedence over the farEnd request.
After media forking is initiated by the web application, the forking can be preserved to continue the recording, even if the WAN connection to the application is lost or if the application is unregistered.
Figure 1-11 Forking Preservation
The “preserve” parameter value can be set to TRUE or FALSE in any of the 3 forking requests (RequestXmfConnectionMediaForking, RequestXmfCallMediaForking, or RequestXmfCallMediaSetAttributes) from the application to voice gateway.