com.cisco.jtapi.extensions
Interface CiscoMediaTerminal

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

public interface CiscoMediaTerminal
extends CiscoTerminal

Introduction

A CiscoMediaTerminal is a special kind of CiscoTerminal that allows applications to terminate RTP media streams. Unlike a CiscoTerminal, a CiscoMediaTerminal does not represent a physical telephony endpoint, which is observable and controllable in a third-party manner. Instead, a CiscoMediaTerminal is a logical telephony endpoint, which may be associated with any application that wants to terminate media. Such applications include voice messaging systems, interactive voice response (IVR), and softphones.

NOTE: Only CTIPorts appear as CiscoMediaTerminals through JTAPI.

Terminating media is a two-step process. To terminate media for a particular terminal, an application first adds an observer that implements the CiscoTerminalObserver interface using the Terminal.addObserver method. Finally, the application registers the IP address and port number to which incoming RTP streams for the terminal should be directed, by using the CiscoMediaTerminal.register method.

To supply an IP address and port number dynamically on a per-call basis, applications must register by only providing the capabilities that they support. Applications must react to the CiscoMediaOpenLogicalChannelEv that gets sent whenever media gets established. Applications registering with this type must be aware that, when this event is received, the far end and the local end may not be able to perform any feature operation unless media is established. If applications fail to respond to this event within the specified time, the call may get dropped.

See Also:
CiscoTerminal

Field Summary
 
Fields inherited from interface com.cisco.jtapi.extensions.CiscoTerminal
APPLICATION, 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, NO_ROLLOVER, NOT_APPLICABLE, OUT_OF_SERVICE, PHONE_USER, ROLLOVER_ANY_DN, ROLLOVER_SAME_DN, UCS2UNICODE_ENCODING, UNKNOWN_ENCODING
 
Method Summary
 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)
          This method registers the MediaTerminal with the specified CiscoMediaCapabilities.
 void register(CiscoMediaCapability[] capabilities, int[] algorithmIDs)
          This method registers a MediaTerminal with the specified CiscoMediaCapabilities and supported SRTP algorithms.
 void register(CiscoMediaCapability[] capabilities, int[] algorithmIDs, int activeAddressingMode)
          The CiscoMediaTerminal must be in the CiscoTerminal.UNREGISTERED state and its Provider must be in the Provider.IN_SERVICE state.
 void register(java.net.InetAddress address, int port)
          Deprecated.  
 void register(java.net.InetAddress address, int port, CiscoMediaCapability[] capabilities)
          This method registers the MediaTerminal.
 void register(java.net.InetAddress address, int port, CiscoMediaCapability[] capabilities, int[] algorithmIDs)
          This method registers the MediaTerminal.
 void register(java.net.InetAddress address, int port, CiscoMediaCapability[] capabilities, int[] algorithmIDs, java.net.InetAddress address_v6, int activeAddressingMode)
          The CiscoMediaTerminal 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 MediaTerminal.
 void setRTPParams(CiscoRTPHandle rtpHandle, CiscoRTPParams rtpParams)
          Applications must use this method when they want to set the IP address and RTP port number to dynamically stream media for a call.
 void unregister()
          This method unregisters the MediaTerminal and returns successfully when the MediaTerminal gets unregistered.
 
Methods inherited from interface com.cisco.jtapi.extensions.CiscoTerminal
canConsultCallRollOver, canDirectTransferAcrossLines, canDirectTransferOnSameLine, canJoinAcrossLines, canJoinOnSameLine, canOutBoundCallRollOver, createSnapshot, getAltScript, getDeviceState, getDNDOption, getDNDStatus, getEMLoginUsername, getFilter, getIPAddressingMode, getIPV4Address, getIPV6Address, getLocale, getProtocol, getRegistrationState, getRollOverConfig, 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
 

Method Detail

register

void register(java.net.InetAddress address,
              int port,
              CiscoMediaCapability[] capabilities)
              throws CiscoRegistrationException
This method registers the MediaTerminal. The CiscoMediaTerminal must be in the CiscoTerminal.UNREGISTERED state and its Provider must be in the Provider.IN_SERVICE state. This method has three arguments. The first argument specifies the internet address at which the RTP media stream for this Terminal will terminate, the second indicates the UDP port at which RTP packets will be directed, and the final argument indicates the type of RTP encodings that the application is willing to support for this Terminal. This method returns successfully when the MediaTerminal is registered.

Parameters:
address - The internet address at which inbound IPv4 RTP streams on this terminal will terminate
port - The UDP port for inbound RTP streams on this terminal
capabilities - The list of the types of RTP encodings that the application supports for this terminal.
Throws:
CiscoRegistrationException

register

void register(java.net.InetAddress address,
              int port)
              throws CiscoRegistrationException
Deprecated. 

Registers a Terminal with the specified address and port, defaulting to G.711 64 kHz u-law encoding with a thirty-millisecond packet size.

Parameters:
address - The internet address for inbound IPv4 RTP streams on this terminal
port - The UDP port for inbound RTP streams on this terminal
Throws:
CiscoRegistrationException

register

void register(java.net.InetAddress address,
              int port,
              CiscoMediaCapability[] capabilities,
              int[] algorithmIDs)
              throws CiscoRegistrationException,
                     javax.telephony.PrivilegeViolationException
This method registers the MediaTerminal. Ensure the CiscoMediaTerminal is in the CiscoTerminal.UNREGISTERED state and its Provider is in the Provider.IN_SERVICE state. This method returns successfully when the MediaTerminal gets registered. This method requires that the application have a TLS link established with CTIManager and have the SRTP Enabled flag enabled in Cisco Unified Communications Manager administration for the user; otherwise, the system throws a PrivilegeViolationException.

Parameters:
address - The internet address for inbound IPv4 RTP streams on this terminal
port - The UDP port for inbound RTP streams on this terminal
capabilities - The list of RTP encodings that this terminal supports
algorithmIDs - The SRTP algorithms that this CTIPort supports. AlgorithmIDs must be one of CiscoMediaEncryptionAlgorithmType.
Throws:
CiscoRegistrationException
javax.telephony.PrivilegeViolationException

register

void register(java.net.InetAddress address,
              int port,
              CiscoMediaCapability[] capabilities,
              int[] algorithmIDs,
              java.net.InetAddress address_v6,
              int activeAddressingMode)
              throws CiscoRegistrationException,
                     javax.telephony.PrivilegeViolationException
The CiscoMediaTerminal 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 MediaTerminal. activeAddressingMode indicates the application's IP Addressing Capabilities, If application specifies activeAddressingMode as CiscoTerminal.IP_ADDRESSING_MODE_IPv4, then it must also specify address If application specifies activeAddressingMode as CiscoTerminal.IP_ADDRESSING_MODE_IPv6, then it must also specify address_v6 If application specifies activeAddressingMode as CiscoTerminal.IP_ADDRESSING_MODE_IPv4_6, then it must also specify address and address_v6
Method Arguments
This method has four arguments. The first argument specifies the internet address at which the RTP media stream for this Terminal will be terminated, the second indicates the UDP port at which RTP packets will be directed, the third argument indicates the type of RTP encodings that the application is willing to support for this Terminal and the final argument indicates SRTP algorithm that application supports. This method can be used only if application has TLS link established with CTIManager and if application has SRTP Enabled flag enabled in CM Admin pages for the user, otherwise PrivilegeViolationException is thrown.
Method Post-conditions
This method returns successfully when the MediaTerminal is registered.

Parameters:
address - the internet address for inbound IPv4 RTP streams on this terminal, it can be null depending on application's Addressing Mode
port - the UDP port for inbound RTP streams on this terminal
capabilities - the list of RTP encodings supported by this terminal
algorithmIDs - indicates SRTP algorithms that this CTIPort supports. AlgorithmIDs may only be one of CiscoMediaEncryptionAlgorithmType
address_v6 - the IPv6 internet address for inbound IPv6 RTP streams on this terminal, it can be null depending upon activeAddressingMode
activeAddressingMode - is IP Addressing mode in which application intends to register this CiscoMediaTerminal, 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

register

void register(CiscoMediaCapability[] capabilities)
              throws CiscoRegistrationException
This method registers the MediaTerminal with the specified CiscoMediaCapabilities. Applications should use this method when they want to supply the IP address and port dynamically for each call. Applications that register with this method will receive a CiscoMediaOpenLogicalChannelEv for each call and must supply an IP address and port number by using the setRTPParams method on this object.

Ensure the CiscoMediaTerminal is in the CiscoTerminal.UNREGISTERED state and its Provider is in the Provider.IN_SERVICE state.

Method Arguments
Arguments indicate the type of RTP encodings that the application is willing to support for this Terminal.
Method Post-conditions
This method returns successfully when the CiscoMediaTerminal is registered.

Parameters:
capabilities - The list of RTP encodings that this terminal supports
Throws:
CiscoRegistrationException
See Also:
CiscoMediaOpenLogicalChannelEv

register

void register(CiscoMediaCapability[] capabilities,
              int[] algorithmIDs)
              throws CiscoRegistrationException,
                     javax.telephony.PrivilegeViolationException
This method registers a MediaTerminal with the specified CiscoMediaCapabilities and supported SRTP algorithms. Applications should use this method when they want to supply the IP address and port dynamically for each call and also want to specify the SRTP algorithm. Applications that register with this method will receive a CiscoMediaOpenLogicalChannelEv for each call and must supply the IP address and port number by using the setRTPParams method on this object. This form of register() also requires a second parameter that indicates which SRTP algorithm that the application supports.

This method requires that the application have a TLS link established with CTIManager and have the SRTP Enabled flag enabled in Cisco Unified Communications Manager administration for the user; otherwise, the system throws a PrivilegeViolationException.

This method returns successfully when the CiscoMediaTerminal gets registered.

Ensure the CiscoMediaTerminal is in the CiscoTerminal.UNREGISTERED state and its Provider is in the Provider.IN_SERVICE state.

Parameters:
capabilities - The list of RTP encodings that this terminal supports
algorithmIDs - The list of SRTP algorithms that this terminal supports. AlgorithmIDs must be one of CiscoMediaEncryptionAlgorithmType.
Throws:
CiscoRegistrationException
javax.telephony.PrivilegeViolationException
See Also:
CiscoMediaOpenLogicalChannelEv

register

void register(CiscoMediaCapability[] capabilities,
              int[] algorithmIDs,
              int activeAddressingMode)
              throws CiscoRegistrationException,
                     javax.telephony.PrivilegeViolationException
The CiscoMediaTerminal 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 MediaTerminal. Registers a Terminal with specified CiscoMediaCapabilities and supported SRTP algorithms. Indicates that application is interested in supplying ipAddress and port dynamically for each call. Applications registering with this method will receive CiscoMediaOpenLogicalChannelEv for each call and will have to supply ipAddress and port number using setRTPParams method on this object. Second param indicates SRTP algorithm that application supports. This method can be used only if application has TLS link established with CTIManager and if application has SRTP Enabled flag enabled in CM Admin pages for the user, otherwise PrivilegeViolationException is thrown.
Method Arguments
Arguments indicate the type of RTP encodings that the application is willing to support for this Terminal and the application or CTIManager failure persistence delay
Method Post-conditions
This method returns successfully when the CiscoMediaTerminal is registered.

Parameters:
capabilities - the list of RTP encodings supported by this terminal
algorithmIDs - indicates the list of SRTP algorithms supported by this terminal. AlgorithmIDs may only be one of CiscoMediaEncryptionAlgorithmType
activeAddressingMode - is the IP Addressing mode in which application intends to register this CiscoMediaTerminal, 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

setRTPParams

void setRTPParams(CiscoRTPHandle rtpHandle,
                  CiscoRTPParams rtpParams)
                  throws javax.telephony.InvalidStateException,
                         javax.telephony.InvalidArgumentException,
                         javax.telephony.PrivilegeViolationException
Applications must use this method when they want to set the IP address and RTP port number to dynamically stream media for a call. In this situation, the application will have registered the MediaTerminal or CiscoRouteTeminal by providing only capabilities. Applications must invoke this method upon receiving the CiscoCallOpenLogicalChannel on terminalObserver. Applications must pass in the rtpHandle that they receive in CiscoCallOpenLogicalChannelEv.

Applications can get a CiscoCall reference by calling the CiscoProvider.getRTPHandle(rtpHandle) method. This method may return null if no call observer is added on the terminal, or there was no callobserver at the time when this event got sent sent, or or there is no call associated with this handle.

Parameters:
rtpHandle - is obtained from CiscoMediaCallOpenLogicalChannelEv
rtpParams - is of type CiscoRTPParams, which is used to specify the dynamic RTP address and port number for a media terminal on a per-call basis.
Throws:
javax.telephony.InvalidStateException
javax.telephony.InvalidArgumentException
javax.telephony.PrivilegeViolationException
See Also:
CiscoRTPParams

unregister

void unregister()
                throws CiscoUnregistrationException
This method unregisters the MediaTerminal and returns successfully when the MediaTerminal gets unregistered. The CiscoMediaTerminal must be registered and its Provider must be in the Provider.IN_SERVICE state.

Throws:
CiscoUnregistrationException

isRegistered

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

Specified by:
isRegistered in interface CiscoTerminal

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 will get set to true until this application unregisters the device.