com.cisco.jtapi.extensions
Interface CiscoRouteTerminal

All Superinterfaces:
CiscoObjectContainer, CiscoTerminal, javax.telephony.Terminal

public interface CiscoRouteTerminal
extends CiscoTerminal

Introduction

A CiscoRouteTerminal is a special kind of CiscoTerminal that allows applications to terminate RTP media streams. Unlike a CiscoTerminal, a CiscoRouteTerminal does not represent a physical telephony endpoint, which is observable and controllable in a third-party manner. Instead, a CiscoRouteTerminal is a logical telephony endpoint that may be associated with any application that wants to route calls and terminate media. Unlike a CiscoMediaTerminal, a CiscoRouteTerminal can have multiple active calls at the same time. Typically, applications use CiscoRouteTerminals to queue calls until an agent is available to service them.

NOTE: CiscoRouteTerminals are CTI Route Points on Cisco Unified Communications Manager.

Terminating media is a three-step process:

  1. The application registers its media capabilities with this Terminal by using the CiscoRouteTerminal.register method.
  2. The application adds an observer that implements the CiscoTerminalObserver interface by using the Terminal.addObserver method.
  3. The application must call addCallObserver on the CiscoRouteTerminal or the CiscoRouteAddress to receive and answer calls.
Applications will receive a CiscoMediaOpenLogicalChannelEv for each call or whenever media is stopped and needs to be reestablished. Applications must supply an IP address and port number by using the setRTPParams method on CiscoRouteTerminal.

Important: All applications written for or prior to CiscoJtapiClient Release 1.4 must be modified to register with CiscoRouteTerminal.NO_MEDIA_TERMINATION type if the applications are not interested in media termination.

Multiple applications can register with same RoutePoint as long as they are registered with the same media capabilities and registration type. All applications, if registered with CiscoRouteTerminal.DYNAMIC_MEDIA_REGISTRATION, will receive CiscoMediaOpenLogicalChannelEv when they add a callObserver, but only one application will be able to invoke setRTPParams.

Applications that are interested in media termination must add a CallObserver on the RouteAddress or on the CiscoRouteTerminals. Applications must not register with Dynamic type and add a registerRouteCallBack. Applications should only use registerRouteCallBack if they are not interested in media termination. Applications must not add a registerRouteCallBack and a callObserver at the same time.

See Also:
CiscoTerminal

Field Summary
static int DYNAMIC_MEDIA_REGISTRATION
          Applications that are interested in media termination need to register with this type and pass in the capabilities that the application supports in the registration request.
static int NO_MEDIA_REGISTRATION
          Applications that are not interested in media termination need to register with this type and pass in a null value for CiscoMediaCapability in the registration request.
 
Fields inherited from interface com.cisco.jtapi.extensions.CiscoTerminal
ASCII_ENCODING, DEVICESTATE_ACTIVE, DEVICESTATE_ALERTING, DEVICESTATE_HELD, DEVICESTATE_IDLE, DEVICESTATE_UNKNOWN, DEVICESTATE_WHISPER, DND_OPTION_CALL_REJECT, DND_OPTION_NONE, DND_OPTION_RINGER_OFF, IN_SERVICE, IP_ADDRESSING_MODE_IPV4, IP_ADDRESSING_MODE_IPV4_V6, IP_ADDRESSING_MODE_IPV6, IP_ADDRESSING_MODE_UNKNOWN, IP_ADDRESSING_MODE_UNKNOWN_ANATRED, NOT_APPLICABLE, OUT_OF_SERVICE, UCS2UNICODE_ENCODING, UNKNOWN_ENCODING
 
Method Summary
 int getIPAddressingMode()
          Application can invoke this API to query the IP Addressing Mode of the CiscoRouteTerminal Addressing mode may be any of the following constants: CiscoTerminal.IP_ADDRESSING_IPv4 CiscoTerminal.IP_ADDRESSING_IPv6 CiscoTerminal.IP_ADDRESSING_IPv4_v6
 boolean isRegistered()
          This method returns true if the CiscoMediaTerminal is registered and false otherwise.
 boolean isRegisteredByThisApp()
          This method returns true if this application issued a successful registration request.
 void register(CiscoMediaCapability[] capabilities, int registrationType)
          Registers a Terminal with specified CiscoMediaCapabilities and register type.
 void register(CiscoMediaCapability[] capabilities, int registrationType, int[] algorithmIDs)
          Registers a Terminal with the specified CiscoMediaCapabilities, registrationType, and supported SRTP algorithms.
 void register(CiscoMediaCapability[] capabilities, int registrationType, int[] algorithmIDs, int activeAddressingMode)
          The CiscoRouteTerminal must be in the CiscoTerminal.UNREGISTERED state and its Provider must be in the Provider.IN_SERVICE state.
 void setRTPParams(CiscoRTPHandle rtpHandle, CiscoRTPParams rtpParams)
          Applications can set the IP address and RTP Port number to dynamically stream media for a call.
 void unregister()
          The CiscoRouteTerminal must be registered and its Provider must be in the Provider.IN_SERVICE state.
 
Methods inherited from interface com.cisco.jtapi.extensions.CiscoTerminal
createSnapshot, getAltScript, getDeviceState, getDNDOption, getDNDStatus, getEMLoginUsername, getFilter, getLocale, getProtocol, getRegistrationState, getRTPInputProperties, getRTPOutputProperties, getState, getSupportedEncoding, isRestricted, sendData, sendData, setDNDStatus, setFilter, unPark
 
Methods inherited from interface javax.telephony.Terminal
addCallObserver, addObserver, getAddresses, getCallObservers, getCapabilities, getName, getObservers, getProvider, getTerminalCapabilities, getTerminalConnections, removeCallObserver, removeObserver
 
Methods inherited from interface com.cisco.jtapi.extensions.CiscoObjectContainer
getObject, setObject
 

Field Detail

NO_MEDIA_REGISTRATION

static final int NO_MEDIA_REGISTRATION
Applications that are not interested in media termination need to register with this type and pass in a null value for CiscoMediaCapability in the registration request. If registrationType is CiscoRouteTerminal.NO_MEDIA_REGISTRATION, the application cannot terminate media and can use the CiscoRouteTerminal for call routing.

See Also:
Constant Field Values

DYNAMIC_MEDIA_REGISTRATION

static final int DYNAMIC_MEDIA_REGISTRATION
Applications that are interested in media termination need to register with this type and pass in the capabilities that the application supports in the registration request.

See Also:
Constant Field Values
Method Detail

register

void register(CiscoMediaCapability[] capabilities,
              int registrationType)
              throws CiscoRegistrationException
Registers a Terminal with specified CiscoMediaCapabilities and register type. The Provider must be in the Provider.IN_SERVICE state. This method returns successfully when the CiscoRouteTerminal is registered.

Parameters:
capabilities - The list of RTP encodings that the application supports for this Terminal. If the application is not interested in media termination, you may pass in a null value.
registrationType - Either CiscoRouteTerminal.DYNAMIC_MEDIA_REGISTRATION or CiscoRouteTerminal.NO_MEDIA_REGISTRATION.

If registrationType is CiscoRouteTerminal.NO_MEDIA_REGISTRATION, the application cannot terminate media and can use the CiscoRouteTerminal for call routing.

If registrationType is CiscoRouteTerminal.DYNAMIC_MEDIA_REGISTRATION, the application can terminate media and can have multiple active calls. This registrationType indicates that the application will supply the IP address and port dynamically for each call. Applications registering with this type receive a CiscoMediaOpenLogicalChannelEv for each call and must supply the IP address and port number by using the setRTPParams method on the CiscoRouteTerminal.

Throws:
CiscoRegistrationException
See Also:
CiscoMediaOpenLogicalChannelEv

register

void register(CiscoMediaCapability[] capabilities,
              int registrationType,
              int[] algorithmIDs)
              throws CiscoRegistrationException,
                     javax.telephony.PrivilegeViolationException
Registers a Terminal with the specified CiscoMediaCapabilities, registrationType, and supported SRTP algorithms. The Provider must be in the Provider.IN_SERVICE state. This method returns successfully when the CiscoRouteTerminal is registered.

Parameters:
capabilities - The list of RTP encodings that the application supports for this Terminal. If the application is not interested in media termination, you may pass in a null value.
registrationType - Either CiscoRouteTerminal.DYNAMIC_MEDIA_REGISTRATION or CiscoRouteTerminal.NO_MEDIA_REGISTRATION.

If registrationType is CiscoRouteTerminal.NO_MEDIA_REGISTRATION, the application cannot terminate media and can use the CiscoRouteTerminal for call routing. Other parameters in the method are ignored.

If registrationType is CiscoRouteTerminal.DYNAMIC_MEDIA_REGISTRATION, the application can terminate media and can have multiple active calls. This registrationType indicates that the application will supply the IP address and port dynamically for each call. Applications registering with this type receive a CiscoMediaOpenLogicalChannelEv for each call and must supply the IP address and port number by using the setRTPParams method on the

algorithmIDs - The list of SRTP algorithms that the application supports for this Terminal. To use this, the application must have the TLS Link and SRTP Enabled flag enabled. AlgorithmIDs must be one of CiscoMediaEncryptionSupportedAlgorithms.
Throws:
javax.telephony.PrivilegeViolationException - The application tried to use the method, but is not authorized to use it.
CiscoRegistrationException
See Also:
CiscoMediaOpenLogicalChannelEv

register

void register(CiscoMediaCapability[] capabilities,
              int registrationType,
              int[] algorithmIDs,
              int activeAddressingMode)
              throws CiscoRegistrationException,
                     javax.telephony.PrivilegeViolationException
The CiscoRouteTerminal must be in the CiscoTerminal.UNREGISTERED state and its Provider must be in the Provider.IN_SERVICE state. The successful effect of this method is to register the RouteTerminal. Registers a Terminal with specified CiscoMediaCapabilities and register type and supported SRTP Algorithms.
  1. If registrationType is CiscoRouteTerminal.NO_MEDIA_REGISTRATION, application cannot terminate media and can use route point for call routing purpose. Other parameters in the method are ignored.
  2. If registration Type is CiscoRouteTerminal.DYNAMIC_MEDIA_REGISTRATION, then app can terminate media and can have multiple active calls. This Indicates that application is interested in supplying ipAddress and port dynamically for each call. Applications registering with this type will receive CiscoMediaOpenLogicalChannelEv for each call and will have to supply ipAddress and port number using setRTPParams method on CiscoRouteTerminal.

Method Arguments
capabilities
  1. indicates the type of RTP encodings that the application is willing to support for this Terminal. If application is not intersted in media termination, it may pass in null value

registrationType may be
  1. CiscoRouteTerminal.NO_MEDIA_REGISTRATION
  2. CiscoRouteTerminal.DYNAMIC_MEDIA_REGISTRATION

  1. supportedAlgorithms may be the SRTP Algorithms that application supports for this terminal. In order to use this, application need to have TLS Link and SRTP Enabled flag enabled. PrivilegeViolationException is thrown if app is not authorized to use this method.
Method Post-conditions
This method returns successfully when the CiscoRouteTerminal is registered.

Parameters:
capabilities - the list of RTP encodings supported by this terminal
registrationType - CiscoRouteTerminal.DYNAMIC_MEDIA_REGISTRATION or CiscoRouteTerminal.NO_MEDIA_REGISTRATION
algorithmIDs - indicates the list of SRTP algorithms supported by this terminal. AlgorithmIDs may only be one of CiscoMediaEncryptionSupportedAlgorithms
activeAddressingMode - is IP Addressing mode in which application intends to register this CiscoRouteTerminal, activeAddressingMode can be: CiscoTerminal.IP_ADDRESSING_MODE_IPv4 or CiscoTerminal.IP_ADDRESSING_MODE_IPv6, or CiscoTerminal.IP_ADDRESSING_MODE_IPv4_v6
Throws:
CiscoRegistrationException
javax.telephony.PrivilegeViolationException
Since:
7.0
See Also:
CiscoMediaOpenLogicalChannelEv

unregister

void unregister()
                throws CiscoUnregistrationException
The CiscoRouteTerminal must be registered and its Provider must be in the Provider.IN_SERVICE state. The successful effect of this method is to unregister the CiscoRouteTerminal.
Method Post-conditions
This method returns successfully when the MediaTerminal is unregistered.

Throws:
CiscoUnregistrationException

setRTPParams

void setRTPParams(CiscoRTPHandle rtpHandle,
                  CiscoRTPParams rtpParams)
                  throws javax.telephony.InvalidStateException,
                         javax.telephony.InvalidArgumentException,
                         javax.telephony.PrivilegeViolationException
Applications can set the IP address and RTP Port number to dynamically stream media for a call. To do this, applications must register MediaTerminal or CiscoRouteTeminal by providing only capabilities. Applications must then invoke this method upon receiving CiscoCallOpenLogicalChannelEv on the TerminalObserver.

Parameters:
rtpHandle - The handle the application receives in CiscoCallOpenLogicalChannelEv
rtpParams - @see CiscoRTPParams
Throws:
javax.telephony.InvalidStateException
javax.telephony.InvalidArgumentException
javax.telephony.PrivilegeViolationException
See Also:
CiscoMediaOpenLogicalChannelEv

isRegistered

boolean isRegistered()
This method returns true if the CiscoMediaTerminal is registered and false otherwise. If the CiscoRouteTerminal is OutOfService, this method returns false; if it is InService, this method returns true. For CTIManager failure cases, this method returns false.


isRegisteredByThisApp

boolean isRegisteredByThisApp()
This method returns true if this application issued a successful registration request. The registration remains valid even if the device is out-of-service because of a CTIManager failure. This returns true until this application unregisters the device.


getIPAddressingMode

int getIPAddressingMode()
Application can invoke this API to query the IP Addressing Mode of the CiscoRouteTerminal Addressing mode may be any of the following constants: