Table Of Contents
Changes to the User Control List in the Directory
Address and Terminal Relationship
Unobserved Addresses and Terminals
CiscoSynchronousObserver Interface
Application Control of JTAPI Parameters
Dynamic Trace Enabling Using Jtprefs
Cisco JTAPI Install Internationalization
Transfer and Conference Extensions
Transfer and Conference Enhancement
Cisco CallManager Media Endpoint Model
Payload and Parameter Negotiation
Starting Transmission and Reception
Stopping Transmission and Reception
Receiving and Responding to Media Flow Events
Inbound Call Media Flow Event Diagram
Cisco IP Telephony Solutions RTP Implementation
Cisco Route Session Implementation
Fault Tolerance When Using Route Points
Cisco CallManager Server Failure
Invoking CTIManager Redundancy
GetCallInfo Interface on Address
VG248 and ATA 186 Analog Phone Gateways
Barge and Privacy Event Notification
CallSelect and UnSelect Event Notification
Dynamic CTIPort Registration Per Call
Media Termination at Route Point
Redirect Set Original Called ID
CiscoTerminal Filter and ButtonPressedEvents
AutoAccept Support for CTIPort and RoutePoint
CiscoTermRegistrationFailed Event
SelectRoute Interface Enhancement
Presentation Indicator (PI) for the Call
Progress State Converted to Disconnect State
Forced Authorization and Client Matter Codes
Forced Authorization Code (FAC)
Call.Connect() and Call.Consult()
Call.transfer(String) and Connection.redirect()
Super Provider (Disable Device Validation)
Q.Signaling (QSIG) Path Replacement
Overview
This chapter introduces the major concepts with which you need to be familiar before creating JTAPI applications for Cisco IP Telephony Solutions. The chapter covers the following concepts:
•
Application Control of JTAPI Parameters
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
Cisco JTAPI
An abstract telephony model, Java Telephony application Programming Interface (JTAPI), can uniformly represent the characteristics of a wide variety of telecommunication systems. Because JTAPI is defined without direct reference to any particular telephony hardware or software, JTAPI offers a well suited method for the task of controlling or observing nearly any telephone system. For instance, a computer program that makes telephone calls by using an implementation of JTAPI for modems might work without modification by using the Cisco JTAPI implementation.
As powerful as an abstraction may be in theory, in practice, programmers often need to know the details of how the JTAPI model represents the underlying components of a particular telephony system. A modem represents a very simple telephony device with limited features. In contrast, the Cisco IP Telephony Solutions product family offers its users a comprehensive list of features and configuration capabilities. Programmers can best leverage the rich features of Cisco IP Telephony Solutions systems by understanding how it fits into the Cisco JTAPI model.
The following sections outline the deviations, if any, from the JTAPI v 1.2 specification or the specifics of the Cisco JTAPI implementation. Cisco JTAPI also provides extensions to the JTAPI v 1.2 specification. These extensions offer additional functionality to the Cisco implementation that is not defined in the specification. The com.cisco.jtapi.extensions package includes the classes and interfaces for the extensions, and Chapter 2, "Cisco JTAPI Extensions," explains them in detail.
CiscoObjectContainer
The CiscoObjectContainer interface allows applications to associate an application defined object to objects that implement this interface. In Cisco JTAPI, the following interfaces extend the CiscoObjectContainer interface:
•
•
•
•
•
•
•
•
•
JtapiPeer and Provider
The Provider object, which gets created through the implementation of the JtapiPeer object, acts as the main point of contact between applications and JTAPI implementations. The Provider object serves as a repository that contains the entire collection of call model objects, Addresses, Terminals, and Calls, controllable at any time by an application.
The JTPREFS applications administer JtapiPeer.getServices(), which returns server names.
The Provider entails two basic processes: initialization and shutdown.
Ensure that the following information is passed in the JtapiPeer.getProvider() method for applications to obtain a CiscoProvider:
•
•
•
•
Applications must include enough descriptive information, so if the appinfo were logged in an alarm, administrators would know which application caused the alarm. Applications should not include hostname or IP address where they reside, nor the time at which they were spawned. Also, ensure that no "=" or ";" characters are included in the appinfo string because they delimit the getProvider () string. When the appinfo is not specified, you can use a generic and quasi-unique name (JTAPI[XXXX]@hostname, where XXXX represents a random four digit number) instead.
The parameters get passed in key value pairs concatenated in a string as follows:
JtapiPeer.getProvider("CTIManagerHostname;login=user;passwd=userpassword;appinfo=Cisco Softphone")
Initialization
The JtapiPeer.getProvider() method returns a Provider object as soon as the TCP link, the initial handshake with the Cisco CallManager, and device list enumeration are complete. The provider now exists in the OUT_OF_SERVICE state. Cisco JTAPI applications must wait for the provider to go to the IN_SERVICE state before the controlled device list is valid. A ProvInServiceEv event gets delivered to an object that is implementing the ProviderObserver interface. Upon an orderly Cisco CallManager shutdown.
Note
Shutdown
When an application calls provider.shutdown(), JTAPI loses communications permanently with the Cisco CallManager, and a ProvShutdownEv event gets delivered to the application. The application can assume that the Provider will not come up again and the application must handle a complete shutdown.
Provider.getTerminals()
This method returns an array of terminals that are created for the devices that are administered in the user control list in the directory. Refer to the Cisco CallManager Administration Guide to administer the user control list.
Provider.getAddresses()
This method returns an array of addresses that are created from the lines that are assigned to the devices that are administered in the user control list in the directory.
Changes to the User Control List in the Directory
If a device is added to the user control list after the JTAPI application starts, a CiscoTermCreatedEv, and the respective CiscoAddrCreatedEv, gets generated and sent to observers that are implementing the CiscoProviderObserver. In addition, applications can monitor the current registration state of the controlled devices, and dynamically track the availability of these devices. The events for an in-service Address or Terminal get delivered to observers that are implementing the CiscoAddressObserver and the CiscoTerminalObserver.
Note
Note
Addresses and Terminals
The Cisco IP Telephony Solutions architecture includes three fundamental types of endpoints: telephone sets, virtual devices (media termination points and route points), and gateways. Of these endpoints, only telephones and media termination points get exposed through the Cisco JTAPI implementation.
Note
Cisco CallManager allows users to configure telephones to have one or more lines, dialable numbers, which multiple telephones may share simultaneously, or lines can be configured for exclusive use by only one telephone at a time. Each line on a telephone can terminate two calls simultaneously, one of which must be on hold.
This operation acts in a similar way to the operation of the "call waiting" feature on home telephones. Figure 1-1 "Telephone Diagram" shows two configurations, Peter and Mary share one telephone line, 5001, while Paul has his own telephone line, 5002.
Figure 1-1 Telephone Diagram
Address and Terminal Relationship
A unique name identifies all types of Cisco CallManager endpoints. Telephone terminal hardware Media Access Control (MAC) address (such as, "SEP0010EB1014") identifies it, whereas the system administrator may assign any name to a media termination point, so long as its name is distinct. For each endpoint that a Provider controls, the Cisco JTAPI implementation uses its administered name to construct a corresponding Terminal object. Terminal objects in turn have one or more Address objects, each of which corresponds to a line on the endpoint. Figure 1-2 "Address and Terminal Relationship" shows a graphical representation of the relationship between Addresses and Terminals.
Figure 1-2 Address and Terminal Relationship
If two or more endpoints share a line (directory number), the corresponding Address object will be related to more than one Terminal object.
Unobserved Addresses and Terminals
Cisco JTAPI learns about calls only when a CallObserver attaches to the terminals/addresses of the Provider. This means that methods such as Provider.getCalls() or Address.getConnections() will return null, even when calls exist at the address, unless a CallObserver attaches to the address. The system also requires adding a CallObserver to the Address or Terminal that is originating a call via the Call.connect(..) method.
Connection
Connections retain their references to calls and addresses forever. So, a connection reference that is obtained from a call event can always be used to obtain the connection call (getCall()) and address (getAddress()).
TerminalConnection
TerminalConnections always retain their references to terminals and connections. So, a terminal connection reference that is obtained from a call event can always be used to obtain the terminal connection terminal (getTerminal()) and connection (getConnection()).
CiscoConnectionID
The CiscoConnectionID object represents a unique object that is associated with each connection in Cisco JTAPI. Applications may use the object itself or the integer representation of the object.
CiscoCallID
The Cisco CallID object represents a unique object that is associated with each connection in Cisco JTAPI. Applications may use the object itself or the integer representation of the object.
Threaded CallBacks
The Cisco JTAPI implementation design allows applications to invoke blocking JTAPI methods such as Call.connect() and TerminalConnection.answer() from within their observer callbacks. This means that applications do not get subjected to the restrictions imposed by the JTAPI 1.2 specification, which cautions applications against using JTAPI methods from within observer callbacks.
CiscoSynchronousObserver Interface
Applications can selectively disable the queuing logic of the Cisco JTAPI implementation by implementing the CiscoSynchronousObserver interface on their observer objects.
This asynchronous behavior does not adversely affect many applications. Applications that would benefit from a coherent call model during observer callbacks, however, can selectively disable the queuing logic of the Cisco JTAPI implementation. By implementing the CiscoSynchronousObserver interface on its observer objects, an application declares deliver synchronous events to its observers. Events that are delivered to synchronous observers will match the states of the call model objects that are queried from within the observer callback.
Note
Querying Dynamic Objects
Beware of querying dynamic objects such as call objects. By the time you get an event, the object (such as, call) may be in a different state than the state that is indicated. For example, by the time you get a CiscoTransferStartEV, the transferred call may have removed all its internal connections.
callChangeEvent()
When the callChangedEvent() method is called, the validity remains guaranteed for any references that are contained in the event. For example, if the event contains a getConnection() method, the application can call this method and get a valid connection reference. Likewise, a getCallingAddress() method guarantees to return a valid Address object.
CiscoConsultCall
For the CiscoConsultCall interface, a reference to a consulting terminal connection gets retained forever.
For example, when processing a CiscoConsultCallActive event, getConsultingTerminalConnection() guarantees to return a valid terminal connection reference. Further, the terminal connection guarantees to provide access to the consulting connection and thus the consulting call.
CiscoTransferStartEv
For the CiscoTransferStartEv, the references to the transferred call, transfer controller and final call in the event will be valid when callChangedEvent() is called. However, getConnections() may or may not return the connections on these calls.
Alarm Services
Part of the general serviceability framework for Cisco IP telephony applications includes support for sending alarms to a service. The com.cisco.services.alarm package defines the alarm components.
An alarm interface and framework support the sending of alarm notifications in XML over TCP to an Alarm Service that is available on the network in a Cisco JTAPI application. The alarm package includes the following features:
•
•
•
•
The overall framework of the Cisco JTAPI alarm system is similar to the existing JTAPI tracing package. Applications must instantiate an AlarmManager for a particular facility code from which alarm objects can be created. Part of the implementation includes DefaultAlarm and DefaultAlarmWriter implementation classes.
Application Control of JTAPI Parameters
The jtapi.ini file includes the various parameters that are required for configuring Cisco JTAPI. Cisco JTAPI looks for the presence of this file in the current Java classpath.
Cisco JTAPI also supports application setting of all the parameters Cisco JTAPI requires. This system allows a single point of application administration, independent of jtapi.ini. The jtapi.ini file provides a starting point for default values but client applications can modify different values without having to specifically modify the jtapi.ini file.
Applications obtain a CiscoJtapiProperties object from the CiscoJtapiPeer and make changes to the parameters by using the accessor and mutator methods. These properties, which apply peer-wide to all the providers that are derived from a CiscoJtapiPeer, must be set prior to the first getProvider () call on that peer.
Different instances of client applications, however, can impose different settings for these parameters. The com.cisco.jtapi.extensions package defines the CiscoJtapiProperties interface.
Jtapi.ini Parameters
Cisco JTAPI gets configured by using parameters in the jtapi.ini. These parameters get modified by using the Jtprefs application, which the Cisco JTAPI installer installs.
The following parameters apply to Cisco JTAPI:
PROTOCOL_DEBUGGING=1
UseSameDirectory=1
JTAPIIMPL_DEBUGGING=1
UseSystemDotOut=0
QueueStatsEnabled=0
PeriodicWakeupInterval=50
RouteSelectTimeout=5000
UseTraceFile=1
ProviderOpenRequestTimeout=200
CtiManagers=cm-server1;cm-server2
Directory=SEAVIEWTraces
DEBUG=1
DesiredServerHeartbeatInterval=30
AlarmServicePort=1444
CTI_DEBUGGING=1
SyslogCollector=
JTAPI_DEBUGGING=1
PeriodicWakeupEnabled=0
NumTraceFiles=10
AlarmServiceHostname=
MISC_DEBUGGING=1
TracePath=.
UseAlarmService=0
CTIIMPL_DEBUGGING=1
WARNING=1
Traces=WARNING;INFORMATIONAL;DEBUG
INFORMATIONAL=1
UseSyslog=0
JtapiPostConditionTimeout=15
JTAPINotificationPort=789
FileNameBase=seaview
CtiRequestTimeout=30
TraceFileSize=1048576
Debugging=JTAPI_DEBUGGING;JTAPIIMPL_DEBUGGING;CTI_DEBUGGING;CTIIMPL_DEBUGGING;PROTOCOL_DEBUGGING;MISC_DEBUGGING
FileNameExtension=log
QueueSizeThreshold=25
ProviderRetryInterval=30
SyslogCollectorUDPPort=514
UseProgressAsDisconnectedDuringErrorEnabled=0
AllowNetworkEventsAfterOffered=0
Dynamic Trace Enabling Using Jtprefs
You will generally want to turn off high-level debugging traces. Typically, tracing at full debug levels imposes a load on the system that is not desirable during normal system operation. For troubleshooting purposes, an administrator can turn tracing on or off dynamically.
Cisco JTAPI supports the dynamic enabling of traces from the Jtprefs administrative application. The application communicates with JTAPI by using a TCP socket and sends a signal to enable or disable the traces. For more details on dynamic tracing, refer to the Cisco CallManager Administration Guide. Ensure that the trace file generation is turned on before using dynamic tracing. If no trace files are being generated, dynamic tracing does not enable file generation. Dynamic tracing only enables or disables traces on an existing log file stream. By default, JTAPI enables file writing with all tracing levels off.
Supported Device Types
Cisco JTAPI supports the following device types:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
Call Forward Setting
Cisco JTAPI supports setting the Call Forward feature according to the JTAPI Specification. Cisco JTAPI implementation does not support all the forwarding characteristics but supports only the FORWARD_ALL attribute for the Address. Applications can invoke setForwarding, getForwarding, and cancelForwarding methods on a CallControlAddress object, but the CallControlForwarding instruction can only be of type FORWARD_ALL.
Call Park
Cisco JTAPI supports user interactions with Call Park and reports the appropriate events to the applications. When a call is parked from an IP phone, the connection that belongs to the parking address moves into Disconnected state, and the associated TerminalConnection moves into Dropped state. A new connection in queued state for the park number gets created.
If an application is monitoring only the address that parked the call, then all existing connections get Disconnected, TerminalConnections get Dropped, and the call moves to Invalid state.
Park Retrieval
When a call is parked from an IP phone, the park number displays on the phone. Any terminal can unpark the call by dialing the park number. When a call is unparked, a new call gets created with connections to unparked address. The CallControlConnection for the park number in the original call, which is in the Queued state, moves to the Disconnected state.
Park Reminder
When a parked call is not retrieved for a specified time, a reminder call returns to the address that parked the call, and Park Number connection moves to the Disconnected state. The call reconnects and moves to the Established state. A terminal connection in Talking state gets created for the address that parked the call.
Park DN Monitor
Cisco JTAPI applications can register to receive events when calls are parked and unparked. CiscoProvCallParkEv events will be delivered to provider observer when the application registers for this feature. To successfully register for this feature the "call park retrieval allowed" flag for the user should be turned on. This flag is available with the user configuration on Cisco CallManager Administration. After registering for this feature, the application will receive CiscoProvCallParkEv events when ever a call is parked or unparked from any device in the cluster.
The following new interfaces allow applications to register and unregister for this feature:
public interface CiscoProvider {public void registerFeature ( int featureID ) throws InvalidStateException, PrivilegeViolationException;public void unregisterFeature ( int featureID ) throws InvalidStateException;}The featureID is CiscoProvFeatureID.MONITOR_CALLPARK_DN
CiscoJtapiExceptions
Cisco JTAPI notifies application of CTI-generated error codes. These codes return when an exception or error occurs in the CTIManager. The CTI returned error code propagates to the application separately. The application can extract the error code by invoking getErrorCode() method on the exception object, can get CTI error code name by invoking getErrorName() method, and can get error description by invoking method getErrorDescription().
The methods getErrorName(int errorCode) and getErrorDescription (int errorCode) deprecate and get' removed in future releases. Cisco recommends that application users do not use these methods.
Cisco JTAPI Install Internationalization
Cisco JTAPI supports multiple languages for the JTAPI installation and user preference UI. When JTAPI launches, you receive options for choosing languages for the installation. After choosing a language, further installation instructions display in the chosen language. The first option always specifies English. If certain phrases are missing in the locale language, the instructions default to English. Refer to the Cisco JTAPI Installation Guide for more installation information.
Clear Calls Interface
Cisco JTAPI applications can clear phantom calls without dropping active calls. The CiscoAddress provides a clearCallConnections message to allow applications to clear the calls when no active calls exist on the Cisco CallManager.
Device Recovery
Cisco JTAPI supports automatic device recovery.
Device Recovery for phones
For devices such as the Cisco IP Phone 7960, the re-homing feature represents part of the device firmware. On a primary Cisco CallManager failure, the phone attempts to connect to the backup Cisco CallManager when it is no longer on a call. This transition gets communicated to applications in the form of out-of-service and in-service events that are described in the CTIManager Failure section.
For virtual devices with no firmware such as CTI Ports and CTI RoutePoints, the the CTIManager or Cisco JTAPI performs the failover.
CTI RoutePoints
On a Cisco CallManager server failure, the CTIManager recovers the device from the Cisco CallManager server group as defined in the device pool administration for the CTI RoutePoint. When the primary Cisco CallManager server recovers, the CTIManager attempts to recover the device on its primary Cisco CallManager. This re-homing happens when no more calls exist on the device, (similar to physical devices). On a CTIManager failure, Cisco JTAPI recovers the device on the backup CTIManager. The application receives notification the availability of a device with the CiscoAddrOutOfServiceEv and CiscoAddrInServiceEv events.
CTI Ports
CTI Ports that are registered by an application include a mechanism similar to phone devices. When the Cisco CallManager that is handling signaling for a CTIPort fails, the CTIManager recovers its services according to the device pool administration for this device. On a CTIManager failure, Cisco JTAPI reregisters the CTI Port after it connects to the backup CTIManager. The CiscoAddrOutOfServiceEv and CiscoTermOutOfServiceEv events and the corresponding in service events get sent after recovery of the CTI Port.
The application controls media streaming for these devices, and streaming continues even when the port is out of service. The application has responsibility to ensure that new calls do not get presented to the device until it is ready to accept them.
Directory Change Notification
Applications require notification asynchronously of device additions or deletions from the user control list and device deletions from the Cisco CallManager database. Applications also receive notification about line changes to a device. This notification gets sent to Cisco JTAPI, propagates to applications with CiscoAddrCreatedEv, CiscoAddrRemovedEv, CiscoTermCreatedEv, and CiscoTermRemovedEv on the AddressObserver and TerminalObservers, respectively.
Note
Enable or Disable Ringer
The CiscoAddress extension allows applications to set the status of the ringer for all lines on a device. No events generate when the ringer setting gets changed from the administration pages or anywhere else.
Transfer and Conference Extensions
You may find that transfer and Conference events are difficult to understand in JTAPI. This happens because the participants are moved from one call to the other, JTAPI represents this action by deleting the parties from one call and adding them to the other call. It may confuse you for an application to receive an indication that a party dropped from the call when, in reality, it is in the process of being moved. The Cisco JTAPI implementation defines some extra events that make it easier for applications to deal with these functions.
Transfer
The transfer feature moves the participants of one call, the transferred call, to another call, the final call. Moving participants in a call results in their associated Connections transitioning to the DISCONNECTED state in the transferred call and new Connections for these participants being created in the final call. Similarly, any associated TerminalConnections transition into the DROPPED state in the transferred call and get created in the final call. Cisco extensions have by definition to mark the start and the end of the events that relate to transfer.
You can correlate the newly created connection objects with the old connection objects by use of the CiscoConnection.getConnectionID() method to obtain the CiscoConnectionID for the old and new connections. Matching connections have identical CiscoConnectionID objects when compared by using the CiscoConnectionID.equals() method.
CiscoTransferStartEv
This event indicates that the transfer operation started, and the events that follow relate to this operation. Specifically, Connections and TerminalConnections get both removed and added as a result of the transfer.
Applications may obtain the two calls that are involved in transfer-transferred call and final call and the transfer controller information from this event. If the JTAPI application is not observing the transfer controller, the transfer controller information does not get made available in this event.
CiscoTransferEndEv
This event indicates that the transfer operation has ended. After this event is received, the application can assume that all involved parties have transferred, and all Connections and TerminalConnections have moved to the final call.
Transfer Scenarios
In the following scenarios, A, B, and C represent three parties that are involved in the transfer.
Consult Transfer, Where B is the Transfer Controller
In a consult transfer, applications can redirect calls to a different address and the transferrer can "consult" with the transfer destination before redirecting.
•
•
•
To do this type of transfer, use the following JTAPI methods:
•
•
•
Note
Table 1-2 lists the core events that observers of A and B receive between the CiscoTransferStartEv and the CiscoTransferEndEv:
Arbitrary Transfer, Where A is the Transfer Controller
In an arbitrary transfer, one call can get transferred to another call, irrespective of how either call was created. Unlike consult transfer, no need exists to first create one of the calls by using the consult method.
•
•
•
•
To do this type of transfer, use the following JTAPI methods:
•
•
Assuming Call1.transfer(Call2) was called, Table 1-3 lists the core events that observers on A and C receive between CiscoTransferStartEv and CiscoTransferEndEv:
Conference
When conferencing two calls together, JTAPI specifies that all the parties from one call be moved to the other call. The call whose parties are moved away and that subsequently becomes invalid gets identified as the "merged" or "consult" call. The call to which the merged parties move gets identified as the "final" call hereafter. When parties move from the merged call to the final call, the application receives events that indicate that all parties dropped from the merged call and events that indicate that the parties reappeared on the final call.
To correlate the newly created connection objects with the old connection objects, use the CiscoConection.getConnectionID() method to obtain CiscoConnectionID objects for all old connections and all new connections. Matching connections will have identical CiscoConnectionID objects when compared by using the CiscoConnectionID.equals() method.
Conference support exists for the following methods:
•
•
•
•
•
Cisco Extensions
Cisco JTAPI implementation provides two extra events that signal the Start and End of Conference: CiscoConferenceStartEv and CiscoConferenceEndEv. These events get sent when Conference initiates and when it completes. They give handles to the final call, the merged conference (consult) call, and the two controlling TerminalConnections (in HELD and TALKING state).
CiscoConferenceStartEv
This event gets sent when call1.conference(call2) is invoked or if the Conference button is pressed for the second time on an IP phone. The ConferenceStartEv signifies the start of the merging process. A sequence of merging events that are reflected by the Conference process in Cisco CallManager follows.
CiscoConferenceEndEv
This event gets sent at the end of the merge process after a ConferenceStartEv is sent. It signifies the completion of the merge of the Consult (or Merged) call into the Final Conference Call. The Merged call specifies in INVALID state and an ObservationEndedEv gets sent for the call observer.
CiscoCall.setConferenceEnable()
The Cisco JTAPI implementation uses the CiscoCall.setConferenceEnable() and the CiscoCall.setTransferEnable() methods to control whether the consult call will be initiated via the conference or the transfer feature. If none of the features is enabled explicitly, transfer gets used by default.
Conference Scenarios
The following scenarios describe the two typical types of Conference that can be invoked.
Consult Conference with B as the Conference Controller
The following sequence of steps typically describes this scenario:
•
•
•
setConferenceEnable()
call2.consult(tc, C)
•
•
Call1.conference(Call2)
Note
Arbitrary Conference with B as the Conference Controller
The following sequence of steps typically describe this scenario:
•
•
•
•
•
•
Call1.conference(Call2) or
Call2.conference(Call1)
Conference Events
Table 1-4 provides the sequence of Core, Call control, and Cisco Extension events when Call1.Conference(Call2) is called:
Transfer and Conference Enhancement
All parties who are involved in the call transfer get sent CiscoTransferStartEv and CiscoTransferEndEv. All parties involved in the call conference get sent CiscoConferenceStartEv and CiscoConferenceEndEv. A call transfer still generates two events—the dropping of a connection to the first call and the creation of a connection to the second call. Cisco CallManager Release 3.1 changed this order of events. Connections first get created in the final call and then get dropped in the consult call.
Note
Note
Consult Without Media
Applications can inform Cisco CallManager that a consultation call for a transfer is being placed without establishing the media path. The system does not require establishing the media path for the intermediate call, if the consultation call is being placed to determine whether an agent is available before the actual transfer. The consultWithoutMedia method as defined in the CiscoConsultCall interface creates a consultation call without establishing the media path.
Note
Media Termination Extensions
The media termination feature allows applications to transmit and capture the bearer of a call, for example, audio or video. This action sometimes gets referred to as "rendering and recording" or "sourcing and sinking" media. It remains distinct from call control because media termination concerns the data that flows between endpoints in a call, not the details of setting up or tearing down calls. For example, an automatic call distributor (ACD) uses call control to route calls among available agents but does not terminate media. An interactive voice response (IVR) application, on the other hand, uses call control to answer and disconnect calls and uses media termination to play sound files to callers.
Although no telephony applications are solely interested in media termination, this feature always gets used in combination with call control. JTAPI 1.2 primarily represents a call control specification and offers very limited support for applications that require media termination. Because the Cisco IP Telephony Solutions platform supports media termination to a much greater degree than JTAPI standard, the Cisco JTAPI implementation extends JTAPI to add full support for this feature.
In Cisco JTAPI, software-based media termination occurs by using Computer Telephony Integration (CTI) ports. They include one or more lines (dialable numbers) that can be used to originate or receive calls. They however need a controlling application to provide the source and sink of the media. An application registers its interest in the media termination port with the Cisco CallManager. The Cisco CallManager then delivers all the events that relate this virtual device to the application. In Cisco JTAPI, CTI Ports get referred to as CiscoMediaTerminals. Figure 1-3 shows the CTI port configuration. For details about administering and configuring a CTI port, refer to the Cisco CallManager Administration web pages.
Figure 1-3 CTI Port Diagram
To implement a softphone application (where the PC acts as the telephone set, for example), the Cisco JTAPI application would manage a CTI port.
Cisco CallManager Media Endpoint Model
Endpoints represent the entities within the Cisco IP Telephony Solutions platform that terminate media, such as IP telephones and gateways. A call from one endpoint to another results in media flowing between the two endpoints. All endpoints in the Cisco IP Telephony Solutions platform transmit voice data by using real-time protocol (RTP). The Cisco IP Telephony Solutions telephones and gateways, for example, include built-in RTP stacks. Applications may also act as endpoints in a Cisco IP Telephony Solutions system; that is, they may terminate media. Because all Cisco IP Telephony Solutions endpoints use RTP, applications also must be able to transmit and receive RTP packets.
Payload and Parameter Negotiation
In addition to bearer data, payload, each RTP packet contains a header that helps endpoints to determine how to reassemble and decode a sequence of such packets into a media stream. RTP does not provide, however, a means for endpoints to negotiate which payload type to use for a particular stream. For example, audio data that is encoded by using the G.711 standard. Furthermore, RTP does not offer a means of negotiating unique payload type parameters such as the sampling rate of the encoded data or the number of samples that are to be transferred in each RTP packet. Instead, RTP usually gets used in conjunction with another protocol such as H.323, which specifies its own method for endpoints to negotiate these parameters. All such negotiation occurs prior to transmitting RTP packets between endpoints.
Cisco CallManager, not the endpoints, has responsibility for selecting the payload and encoding parameters for RTP streams. The following five steps that are involved in a typical bidirectional audio telephone call apply:
•
•
•
•
•
Initialization
Upon startup, each endpoint informs Cisco CallManager of its media capabilities, that is, G.711, G.723, G.729a, and so on. Startup for an IP phone for example, occurs when the phone is first turned on, or after it recontacts Cisco CallManager after losing its former connection. The endpoint cannot express a preference for one payload type versus another, but it can specify certain parameters for each payload type, such as, packet size.
The capability list that the endpoint registers remains exclusive and immutable. If the endpoint specifies that it can support both G.711 and G.723, it implicitly declares that it cannot support G.729a. Moreover, the endpoint must disconnect from Cisco CallManager and reinitialize to change the list of capabilities that it supports.
JTAPI applications perform this step by registering a CiscoMediaTerminal with Cisco CallManager. The CiscoMediaTerminal.register() method allows applications to supply an array of media capability objects for registration with Cisco CallManager. This step informs Cisco CallManager that the application will act as the endpoint for all calls to or from a particular directory number, as determined by the device configuration in the Cisco CallManager configuration.
Payload Selection
When a bidirectional media stream is about to be created between two endpoints, for instance, when a call is answered at an endpoint, Cisco CallManager selects an appropriate payload type (codec) for the media stream. Cisco CallManager compares the media capabilities of both endpoints that are involved in the call and selects the appropriate common payload type and payload parameters to use.
The basis for payload selection includes endpoint capabilities and location, although other criteria may get added to this selection logic in the future. Endpoints do not get dynamically involved in selecting payload types on a call-by-call basis.
Receive Channel Allocation
If Cisco CallManager can find a common payload type for the RTP stream between the two endpoints, it requests that each endpoint create a logical "receive channel;" that is, a unique IP address and port at which the endpoint will receive RTP data for the call. Each endpoint returns an IP address and port to Cisco CallManager in response to this request.
Currently, only IP phones and gateways perform this step. Cisco CallManager requires JTAPI applications to specify a fixed IP address and port during initialization. Therefore, JTAPI applications cannot terminate more than one media stream simultaneously for the same endpoint. Applications that want to terminate multiple media streams must register multiple endpoints simultaneously.
If the endpoint does not respond to the open receive channel request quickly enough, Cisco CallManager disconnects the call. Because JTAPI applications always supply an IP address when registering CiscoMediaTerminals, calls to application-controlled endpoints do not get disconnected for this reason. However, if Cisco CallManager cannot find a common payload type between the two endpoints that are involved in the call, Cisco CallManager disconnects the call.
Starting Transmission and Reception
After Cisco CallManager receives channel information for both parties, it informs each endpoint of the codec parameters that it selected for the RTP stream and the destination address for the other endpoint. This information gets conveyed in two messages to each endpoint: a start transmission message and a start reception message.
JTAPI applications receive the CiscoRTPOutputStartedEv and CiscoRTPInputStartedEv events that contain all the codec parameters that are necessary for sending and receiving RTP data.
Stopping Transmission and Reception
When the RTP stream must be interrupted because of a feature such as hold or disconnect, Cisco CallManager requests that each endpoint stop its transmission and reception of RTP data. Just as when the media flow is started, the stop transmission and stop reception messages get sent separately.
JTAPI applications receive the CiscoRTPOutputStoppedEv and CiscoRTPInputStoppedEv.
CiscoMediaTerminal
In JTAPI, the terminal object represents the logical endpoint for a call and is presumed to be able to receive and transmit data (digital encoded voice samples, for example). Thus, terminals in JTAPI represent Cisco IP Phones. Even though gateways terminate media, terminals do not represent them. The CiscoMediaTerminals in particular represent a special kind of endpoint for which applications take responsibility for media termination.
The following four steps associate with using CiscoMediaTerminals:
•
•
•
•
Provisioning
CiscoMediaTerminals, which are analogous to physical terminals, must be provisioned accordingly in Cisco CallManager, even though they do not represent actual hardware IP phones or gateways. Just as IP phones must be added to Cisco CallManager database by using the Device Wizard, CiscoMediaTerminals get added the same way, so Cisco CallManager can associate the application endpoint with a directory number and other call control properties such as call forwarding. No device type called "CiscoMediaTerminal" exists in the DeviceWizard. Instead, Cisco CallManager has one or more device types that support application registration—each of these types get exposed as a CiscoMediaTerminal through JTAPI. Currently, only the device type "CTI port" represents a CiscoMediaTerminal in JTAPI.
The following procedure lists the steps for provisioning a CTI port for use as an application-controlled endpoint.
Procedure
Step 1
Step 2
For more information, refer to the Cisco CallManager Administration Guide.
Registration
After a media termination device is properly provisioned in Cisco CallManager, the application may obtain a reference to the corresponding CiscoMediaTerminal object by using either the Provider.getTerminal() method or CiscoProvider.getMediaTerminal() method. The the two methods differ in that the CiscoProvider.getMediaTerminal() method only returns CiscoMediaTerminals, whereas Provider.getTerminal() will return any terminal object that is associated with the provider, including those representing physical IP phones.
Use the CiscoMediaTerminal.register() method to notify Cisco CallManager of their intent to terminate RTP streams of certain payload types. The CiscoMediaTermina.register() method takes an IP address, a port number, and an array of CiscoMediaCapability objects that indicate the types of codecs that are supported by the application as well as codec-specific parameters.
The IP address and port indicate the address where the application desires to receive media streams. The following sample code demonstrates how to register a CiscoMediaTerminal and bind it to a local address, port number 1234:
CiscoMediaTerminal registerTerminal (Provider provider, String terminalName) {final int PORT_NUMBER = 1234;try {CiscoMediaTerminal terminal = provider.getTerminal (terminalName);CiscoMediaCapability [] caps = new CiscoMediaCapability [1];caps[0] = CiscoMediaCapability.G711_64K_30_MILLISECONDS;terminal.register (InetAddress.getLocalHost (), PORT_NUMBER, caps);}catch (Exception e) {return null;}}For this sample code to work, the specified provider must be IN_SERVICE. Further, note that this code uses the constant CiscoMediaCapability.G711_64K_30_MILLISECONDS. This actually represents a static reference to a CiscoG711MediaCapability object that specifies a 30-millisecond maximum RTP packet size. The CiscoMediaCapability class predefines this and other common media formats.
To specify a media payload that is not listed in the CiscoMediaCapability class, two options exist. If the desired payload type is a simple variation of one of the existing subclasses of CiscoMediaCapability, you only need to construct a new instance of the subclass. For instance, if an application is willing to support G.711 payloads with a 60-millisecond maximum RTP packet size, it can construct the CiscoG711MediaCapability object directly, specifying 60 milliseconds in the constructor.
On the other hand, if no existing subclass of CiscoMediaCapability that matches the desired payload type exists, construct an instance of the CiscoMediaCapability class directly. The maximum packet size, for example, 30-milliseconds, represents the only other parameter that may be specified when constructing a CiscoMediaCapability. The following code illustrates registering a custom payload capability:
CiscoMediaTerminal registerTerminal (Provider provider, String terminalName) {final int PORT_NUMBER = 1234;try {CiscoMediaTerminal terminal = provider.getTerminal (terminalName);CiscoMediaCapability [] caps = new CiscoMediaCapability [1];caps[0] = new CiscoMediaCapability (RTPPayload.G728,30 // maximum packet size, in milliseconds);terminal.register (InetAddress.getLocalHost (), PORT_NUMBER, caps);}catch ( Exception e) {return null;}}The payload type parameter that is used for constructing the CiscoMediaCapability object corresponds to the payload field in the RTP header. The RTPPayload interface defines a number of well-known payload types for this purpose.
Adding Observers
To receive events that indicate where and when to transmit and receive RTP data, place a CiscoTerminalObserver on the CiscoMediaTerminal. The CiscoTerminalObserver extends the standard JTAPI TerminalObserver interface without defining any new methods; it provides a marker interface that signals the application interest in receiving RTP events.
Note
Additionally, add a CallControlCallObserver to the Address object that is associated with the CiscoMediaTerminal. This guarantees that the application will get notified when calls are offered to the CiscoMediaTerminal. Unlike regular IP phones, which automatically accept any offered call, CiscoMediaTerminals accept, disconnect (reject), or redirect any call that is offered to it. Because the CallCtlConnOfferedEv is only presented to CallControlCallObservers that are placed on Address objects, not Terminal objects, the application places its CallControlCallObserver in the correct place.
Note
Accepting Calls
When an inbound call arrives at the CiscoMediaTerminal address, it must be accepted by using the CallControlConnection.accept() method before a terminal connection gets created. This process does not apply for outbound calls —the connection will occur in the CallControlConnection.ESTABLISHED state as soon as the call progresses beyond digit recognition. After the connection is accepted, answer the ringing terminal connection to start media flow. Assuming that Cisco CallManager can match the capabilities that were registered with the capabilities of the calling endpoint, Cisco CallManager sends the Media Flow events, so the application can begin transmitting and receiving RTP data.
Receiving and Responding to Media Flow Events
Whenever a media stream must be created between two endpoints, Cisco CallManager issues start transmission and start reception events to both endpoints. In JTAPI, the CiscoRTPOutputStartedEv and CiscoRTPInputStartedEv events represent the start transmission and start reception events. The CiscoRTPOutputStartedEv.getRTPOutputProperties() method returns a CiscoRTPOutputProperties object, from which the application can determine the destination address of its peer endpoint in the call, as well as the other RTP properties for the stream such as payload type and packet size. Similarly, the CiscoRTPInputStartedEv.getRTPInputProperties() method returns a CiscoRTPInputProperties object that informs the application of the RTP characteristics for the inbound stream.
At any time while media is flowing, the current CiscoRTPOutputProperties and CiscoRTPInputProperties also remain available from the CiscoMediaTerminal.getRTPOutputProperties() and CiscoMediaTerminal.getRTPInputProperties() methods as well. These methods throw an exception if the CiscoMediaTerminal is not currently supposed to transmit or receive media.
When Cisco CallManager wants the application to stop sending or receiving media as the result of a call disconnecting or being put on hold, for example, it sends the CiscoRTPOutputStoppedEv and CiscoRTPInputStoppedEv events. These events mean that the current RTP media stream that exists between the two endpoints should be torn down.
Inbound Call Media Flow Event Diagram
Table 1-5 illustrates the dialogue between Cisco CallManager and a JTAPI application when a call is presented to an application-controlled endpoint. The events in the left column represent JTAPI events that are sent to the CallObserver of the application, and the requests in the left column represent methods that the application invokes.
