com.cisco.jtapi.extensions
Interface CiscoTerminal

All Superinterfaces:
CiscoObjectContainer, javax.telephony.Terminal
All Known Subinterfaces:
CiscoMediaTerminal, CiscoRouteTerminal

public interface CiscoTerminal
extends javax.telephony.Terminal, CiscoObjectContainer

Introduction

Standard JTAPI does not support the notion of dynamic terminal registration. The CiscoTerminal interface extends the standard terminal interface to do so. All Cisco Unified Communications Manager devices are represented by CiscoTerminals, and you can query all CiscoTerminals to determine whether they are currently IN_SERVICE or OUT_OF_SERVICE.

If the Cisco Unified Communications Manager device represented by the CiscoTerminal is an IP telephone, for instance, it goes OUT_OF_SERVICE if it loses its network connection. Other types of devices, such as CiscoMediaTerminal, get registered on demand by applications, and may be IN_SERVICE or OUT_OF_SERVICE accordingly.

See Also:
Terminal, CiscoMediaTerminal

Field Summary
static int ASCII_ENCODING
          Indicates that the CiscoTerminal.getSupportedEncoding () for this terminal is ASCII and that this terminal supports only ASCII_ENCODING.
static int DEVICESTATE_ACTIVE
          This constant value returned by the getDeviceState() interface on CiscoTerminal indicates that the CiscoTerminal has at least one active call on an Address.
static int DEVICESTATE_ALERTING
          This constant value returned by the getDeviceState() interface on CiscoTerminal indicates that the CiscoTerminal has at least one alerting call, but no active call, on an Address.
static int DEVICESTATE_HELD
          This constant value returned by the getDeviceState() interface on CiscoTerminal indicates that the CiscoTerminal has at least one held call, but no alerting or active calls, on an Address.
static int DEVICESTATE_IDLE
          This constant value returned by the getDeviceState() interface on CiscoTerminal indicates that the CiscoTerminal currently has no calls on any Addresses.
static int DEVICESTATE_UNKNOWN
          This constant value returned by the getDeviceState() interface on CiscoTerminal indicates that the CiscoTerminal DeviceState is Unknown.
static int DEVICESTATE_WHISPER
          This constant value returned by the getDeviceState() interface on CiscoTerminal indicates that the CiscoTerminal has at least one intercom call with one-way media, but has no held, alerting, or active calls on an Address.
static int DND_OPTION_CALL_REJECT
          This constant value returned by the getDNDOptions() interface on CiscoTerminal indicates that the DND option configured is Call Reject.
static int DND_OPTION_NONE
          This constant value returned by the getDNDOption() interface on CiscoTerminal indicates that the DND option configured is None.
static int DND_OPTION_RINGER_OFF
          This constant value returned by the getDNDOption() interface on CiscoTerminal indicates that the DND option configured is Ringer Off.
static int IN_SERVICE
          This constant value returned by the getState() interface on CiscoTerminal indicates that the CiscoTerminal is in service.
static int IP_ADDRESSING_MODE_IPV4
          This indicates that IPAddressing mode is IPv4
static int IP_ADDRESSING_MODE_IPV4_V6
          This indicates that IPAddressing mode is dual stack (IPv4 and IPv6 both)
static int IP_ADDRESSING_MODE_IPV6
          This indicates that IPAddressing mode is IPv6
static int IP_ADDRESSING_MODE_UNKNOWN
          This indicates that IPAddressing mode is Unknown
static int IP_ADDRESSING_MODE_UNKNOWN_ANATRED
          This is reserved IPAddressing constant for ANAT in CUCM, not used in JTAPI
static int NOT_APPLICABLE
          Indicates that the CiscoTerminal.getSupportedEncoding () for this CiscoMediaTerminal or RoutePoint is NOT_APPLICABLE.
static int OUT_OF_SERVICE
          This constant value returned by the getState() interface on CiscoTerminal indicates that the CiscoTerminal is out of service.
static int UCS2UNICODE_ENCODING
          Indicates that the CiscoTerminal.getSupportedEncoding () for this terminal is UCS2UNICODE_ENCODING.
static int UNKNOWN_ENCODING
          Indicates that the CiscoTerminal.getSupportedEncoding () for this terminal is UNKNOWN.
 
Method Summary
 void createSnapshot()
          Generates a CiscoTermSnapshotEv event, which contains the security status of the current active call on the terminal.
 java.lang.String getAltScript()
          Returns the locale alternate script that this terminal supports.
 int getDeviceState()
          Returns the DeviceState of this terminal.
 int getDNDOption()
          Returns the value of the DND option.
 boolean getDNDStatus()
          Reports the DND status.
 java.lang.String getEMLoginUsername()
          Returns Extension mobility(EM) Login UserName If no EM user has logged into Terminal, this interface will return null/empty string
 CiscoTermEvFilter getFilter()
          Retrieves the filter object associated with the terminal.
 int getIPAddressingMode()
          Application can invoke this API to query the IP Addressing Mode of the CiscoTerminal Addressing mode may be any of the following constants: CiscoTerminal.IP_ADDRESSING_IPv4 CiscoTerminal.IP_ADDRESSING_IPv6 CiscoTerminal.IP_ADDRESSING_IPv4_v6
 int getLocale()
          Returns the locale that this terminal supports.
 int getProtocol()
          Reports the terminal protocol (SCCP, SIP, or none).
 int getRegistrationState()
          Deprecated. This method has been replaced by the getState() method.
 CiscoRTPInputProperties getRTPInputProperties()
          Returns the properties to be used for the RTP input stream associated with the ACTIVE TerminalConnection on this terminal.
 CiscoRTPOutputProperties getRTPOutputProperties()
          Returns the properties to be used for the RTP output stream associated with the ACTIVE TerminalConnection on this terminal.
 int getState()
          Returns the state of this terminal.
 int getSupportedEncoding()
          Returns the supported encoding types for this terminal.
 boolean isRestricted()
          Returns the restriction status of this terminal.
 byte[] sendData(byte[] terminalData)
          Sends data to the phone.
 java.lang.String sendData(java.lang.String terminalData)
          Deprecated.  
 void setDNDStatus(boolean dndStatus)
          Sets the DND status, which enables or disables the DND feature.
 void setFilter(CiscoTermEvFilter terminalEvFilter)
          Filters the events that get delivered to the TerminalObserver.
 javax.telephony.TerminalConnection unPark(javax.telephony.Address UnParkAddress, java.lang.String ParkedAt)
          Unparks a call at a terminal and returns a terminalConnection.
 
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

OUT_OF_SERVICE

static final int OUT_OF_SERVICE
This constant value returned by the getState() interface on CiscoTerminal indicates that the CiscoTerminal is out of service.

See Also:
Constant Field Values

IN_SERVICE

static final int IN_SERVICE
This constant value returned by the getState() interface on CiscoTerminal indicates that the CiscoTerminal is in service.

See Also:
Constant Field Values

DEVICESTATE_IDLE

static final int DEVICESTATE_IDLE
This constant value returned by the getDeviceState() interface on CiscoTerminal indicates that the CiscoTerminal currently has no calls on any Addresses.

See Also:
Constant Field Values

DEVICESTATE_ACTIVE

static final int DEVICESTATE_ACTIVE
This constant value returned by the getDeviceState() interface on CiscoTerminal indicates that the CiscoTerminal has at least one active call on an Address.

See Also:
Constant Field Values

DEVICESTATE_ALERTING

static final int DEVICESTATE_ALERTING
This constant value returned by the getDeviceState() interface on CiscoTerminal indicates that the CiscoTerminal has at least one alerting call, but no active call, on an Address.

See Also:
Constant Field Values

DEVICESTATE_HELD

static final int DEVICESTATE_HELD
This constant value returned by the getDeviceState() interface on CiscoTerminal indicates that the CiscoTerminal has at least one held call, but no alerting or active calls, on an Address.

See Also:
Constant Field Values

DEVICESTATE_UNKNOWN

static final int DEVICESTATE_UNKNOWN
This constant value returned by the getDeviceState() interface on CiscoTerminal indicates that the CiscoTerminal DeviceState is Unknown. This state may get returned if the device state filters are disabled.

See Also:
CiscoTermEvFilter, Constant Field Values

DEVICESTATE_WHISPER

static final int DEVICESTATE_WHISPER
This constant value returned by the getDeviceState() interface on CiscoTerminal indicates that the CiscoTerminal has at least one intercom call with one-way media, but has no held, alerting, or active calls on an Address.

See Also:
Constant Field Values

UNKNOWN_ENCODING

static final int UNKNOWN_ENCODING
Indicates that the CiscoTerminal.getSupportedEncoding () for this terminal is UNKNOWN.

See Also:
Constant Field Values

NOT_APPLICABLE

static final int NOT_APPLICABLE
Indicates that the CiscoTerminal.getSupportedEncoding () for this CiscoMediaTerminal or RoutePoint is NOT_APPLICABLE.

See Also:
Constant Field Values

ASCII_ENCODING

static final int ASCII_ENCODING
Indicates that the CiscoTerminal.getSupportedEncoding () for this terminal is ASCII and that this terminal supports only ASCII_ENCODING.

See Also:
Constant Field Values

UCS2UNICODE_ENCODING

static final int UCS2UNICODE_ENCODING
Indicates that the CiscoTerminal.getSupportedEncoding () for this terminal is UCS2UNICODE_ENCODING.

See Also:
Constant Field Values

DND_OPTION_NONE

static final int DND_OPTION_NONE
This constant value returned by the getDNDOption() interface on CiscoTerminal indicates that the DND option configured is None.

See Also:
Constant Field Values

DND_OPTION_RINGER_OFF

static final int DND_OPTION_RINGER_OFF
This constant value returned by the getDNDOption() interface on CiscoTerminal indicates that the DND option configured is Ringer Off. If DND is enabled on the phone, the phone would not ring if a call lands there.

See Also:
Constant Field Values

DND_OPTION_CALL_REJECT

static final int DND_OPTION_CALL_REJECT
This constant value returned by the getDNDOptions() interface on CiscoTerminal indicates that the DND option configured is Call Reject. If DND is enabled on the phone, all calls to the phone will get rejected, except for shared lines.

See Also:
Constant Field Values

IP_ADDRESSING_MODE_UNKNOWN

static final int IP_ADDRESSING_MODE_UNKNOWN
This indicates that IPAddressing mode is Unknown

Since:
7.0
See Also:
Constant Field Values

IP_ADDRESSING_MODE_IPV4

static final int IP_ADDRESSING_MODE_IPV4
This indicates that IPAddressing mode is IPv4

Since:
7.0
See Also:
Constant Field Values

IP_ADDRESSING_MODE_IPV6

static final int IP_ADDRESSING_MODE_IPV6
This indicates that IPAddressing mode is IPv6

Since:
7.0
See Also:
Constant Field Values

IP_ADDRESSING_MODE_IPV4_V6

static final int IP_ADDRESSING_MODE_IPV4_V6
This indicates that IPAddressing mode is dual stack (IPv4 and IPv6 both)

Since:
7.0
See Also:
Constant Field Values

IP_ADDRESSING_MODE_UNKNOWN_ANATRED

static final int IP_ADDRESSING_MODE_UNKNOWN_ANATRED
This is reserved IPAddressing constant for ANAT in CUCM, not used in JTAPI

Since:
7.0
See Also:
Constant Field Values
Method Detail

getRegistrationState

int getRegistrationState()
Deprecated. This method has been replaced by the getState() method.

Returns the state of this terminal.

The state may be any of the following constants:

Returns:
The state of this terminal

getState

int getState()
Returns the state of this terminal.

The state may be any of the following constants:

Returns:
the state of this terminal

getRTPInputProperties

CiscoRTPInputProperties getRTPInputProperties()
                                              throws javax.telephony.InvalidStateException
Returns the properties to be used for the RTP input stream associated with the ACTIVE TerminalConnection on this terminal. The CiscoTerminal must be in the CiscoTerminal.REGISTERED state, its Provider must be in the Provider.IN_SERVICE state, and Terminal.getTerminalConnections () must return at least one terminal connection in the TerminalConnection.ACTIVE state.

Returns:
RTP input stream properties that are associated with the ACTIVE TerminalConnection on this terminal
Throws:
javax.telephony.InvalidStateException

getRTPOutputProperties

CiscoRTPOutputProperties getRTPOutputProperties()
                                                throws javax.telephony.InvalidStateException
Returns the properties to be used for the RTP output stream associated with the ACTIVE TerminalConnection on this terminal. The CiscoTerminal must be in the CiscoTerminal.REGISTERED state, its Provider must be in the Provider.IN_SERVICE state, and Terminal.getTerminalConnections () must return at least one terminal connection in the TerminalConnection.ACTIVE state.

Returns:
RTP output stream properties that are associated with the ACTIVE TerminalConnection on this terminal
Throws:
javax.telephony.InvalidStateException

sendData

java.lang.String sendData(java.lang.String terminalData)
                          throws javax.telephony.InvalidStateException,
                                 javax.telephony.MethodNotSupportedException
Deprecated. 

Deprecated. Use CiscoTerminal.sendData ( byte[] ).

Throws:
javax.telephony.InvalidStateException
javax.telephony.MethodNotSupportedException

sendData

byte[] sendData(byte[] terminalData)
                throws javax.telephony.InvalidStateException,
                       javax.telephony.MethodNotSupportedException
Sends data to the phone. The CiscoTerminal must be in the CiscoTerminal.IN_SERVICE state, and its Provider must be in the Provider.IN_SERVICE state. Applications can push the XSI object in the byte format to the phone with this interface. If the phone receives the data, this method returns successfully. Applications may only send 2000 bytes of data with this interface. Requests carrying excess data get rejected.

Throws:
PlatformException - The data did not get sent successfully.
javax.telephony.InvalidStateException
javax.telephony.MethodNotSupportedException

getFilter

CiscoTermEvFilter getFilter()
Retrieves the filter object associated with the terminal.


setFilter

void setFilter(CiscoTermEvFilter terminalEvFilter)
Filters the events that get delivered to the TerminalObserver. You can call this method at any time, but the typical usage is to set up the terminal events as part of initialization or when a CiscTermCreatedEv indicates that the system created a new terminal.

Example 1: One use might be to turn on the button-pressed events that normally do not get not delivered.

 Terminal term = provider.getTerminal ( name );
 if ( term instanceof CiscoTerm ) {
  CiscoTerm ciscoTerm = (CiscoTerm)term;
        CiscoTermEvFilter filter = ciscoTerm.getFilter ();
        filter.setButtonPressedEnabled ( true );
 }
 term.addObserver ( terminalObserver );
 

Example 2: Another use might be turning off events that are not of interest to an application. For example, an application doing pure call control could turn off the media (RTP) events as follows:

 Terminal term = provider.getTerminal ( name );
 if ( term instanceof CiscoTerm ) {
  CiscoTerm ciscoTerm = (CiscoTerm)term;
        CiscoTermEvFilter filter = ciscoTerm.getFilter ();
  filter.setRTPEventsEnabled ( false );
  ciscoTerm.setFilter ( filter );
 }
 term.addObserver ( terminalObserver );
 term.getAddresses () [0].addCallObserver ( callObserver );
 

Note:
Adding a CallObserver (without explicitly setting a filter) turns the RTP events on. This behaviour of Cisco JTAPI Release 1.4 and earlier is still preserved. If an explicit setFilter call gets made, the filter settings will take effect. The RTP events will not get delivered for the previous code snippet, but will get delivered for the following example:

 Terminal term = provider.getTerminal ( name );
 term.addObserver ( terminalObserver );
 term.getAddresses () [0].addCallObserver ( callObserver );
 


unPark

javax.telephony.TerminalConnection unPark(javax.telephony.Address UnParkAddress,
                                          java.lang.String ParkedAt)
                                          throws javax.telephony.InvalidStateException,
                                                 javax.telephony.InvalidArgumentException,
                                                 javax.telephony.ResourceUnavailableException
Unparks a call at a terminal and returns a terminalConnection. The CiscoTerminal must be in the CiscoTerminal.IN_SERVICE state and its Provider must be in the Provider.IN_SERVICE state. This method takes an address and string as input.

Parameters:
UnParkAddress - Any address on the terminal
ParkedAt - A string identifying is system park port where a call was previously parked. The system returns this string when the call gets parked.
Throws:
javax.telephony.InvalidStateException - The CiscoTerminal.getState() is not IN_SERVICE.
PlatformException - Any other error occurred while unparking (for example, the Unpark number is not valid).
javax.telephony.InvalidArgumentException
javax.telephony.ResourceUnavailableException

getDeviceState

int getDeviceState()
                   throws javax.telephony.InvalidStateException
Returns the DeviceState of this terminal. The DeviceState is the accumulative call state of all the addresses on the terminal. The state may be any of the following constants:

Returns:
The DeviceState of this terminal
Throws:
javax.telephony.InvalidStateException - CiscoTerminal.getState() is not IN_SERVICE.

getSupportedEncoding

int getSupportedEncoding()
                         throws javax.telephony.InvalidStateException
Returns the supported encoding types for this terminal. Use this method to check whether a terminal supports Unicode. To access this information, the terminal must be in the CiscoTerminal.IN_SERVICE state. The supportedEncoding is one of the following constants:

Returns:
The supportedEncoding of this terminal
Throws:
javax.telephony.InvalidStateException

getLocale

int getLocale()
              throws javax.telephony.InvalidStateException
Returns the locale that this terminal supports. To access this method, the terminal must be in the CiscoTerminal.IN_SERVICE state.

Throws:
javax.telephony.InvalidStateException - CiscoTerminal.getState() is not IN_SERVICE.

isRestricted

boolean isRestricted()
Returns the restriction status of this terminal. If a terminal is restricted, all associated addresses on the terminal are also restricted.

Returns:
True if terminal is restricted; otherwise false
See Also:
CiscoAddress.getRestrictedAddrTerminals()

createSnapshot

void createSnapshot()
                    throws javax.telephony.InvalidStateException
Generates a CiscoTermSnapshotEv event, which contains the security status of the current active call on the terminal. To access this method, the terminal must be in the CiscoTerminal.IN_SERVICE state and CiscoTermEvFilter.setSnapshotEnabled () must be set to true.

Throws:
javax.telephony.InvalidStateException - CiscoTerminal.getState() is not IN_SERVICE.

getAltScript

java.lang.String getAltScript()
                              throws javax.telephony.InvalidStateException
Returns the locale alternate script that this terminal supports. An empty return value indicates that this terminal does not support or is not configured with an alternate script. To access this method, the terminal must be in the CiscoTerminal.IN_SERVICE state.

Throws:
javax.telephony.InvalidStateException - CiscoTerminal.getState() is not IN_SERVICE.

getProtocol

int getProtocol()
Reports the terminal protocol (SCCP, SIP, or none).

Returns:
The protocol of this terminal, one of the following constants:
  • CiscoTerminalProtocol.PROTOCOL_NONE
  • CiscoTerminalProtocol.PROTOCOL_SCCP
  • CiscoTerminalProtocol.PROTOCOL_SIP

setDNDStatus

void setDNDStatus(boolean dndStatus)
                  throws javax.telephony.InvalidStateException
Sets the DND status, which enables or disables the DND feature. This feature does not apply to route points.

Parameters:
dndStatus -
Throws:
javax.telephony.InvalidStateException - CiscoTerminal.getState() is not IN_SERVICE.

getDNDStatus

boolean getDNDStatus()
                     throws javax.telephony.InvalidStateException
Reports the DND status.

Returns:
boolean dndStatus
Throws:
javax.telephony.InvalidStateException - CiscoTerminal.getState() is not IN_SERVICE.

getDNDOption

int getDNDOption()
                 throws javax.telephony.InvalidStateException
Returns the value of the DND option. This value is not significant for a CiscoMediaTerminal or CiscoRouteTerminal because the DND feature applies only to physical phones. The DND option can be any of the following constants:

Returns:
int The value of the DND option currently set for this CiscoTerminal.
Throws:
javax.telephony.InvalidStateException - CiscoTerminal.getState() is not IN_SERVICE.

getIPAddressingMode

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

getEMLoginUsername

java.lang.String getEMLoginUsername()
                                    throws javax.telephony.InvalidStateException
Returns Extension mobility(EM) Login UserName If no EM user has logged into Terminal, this interface will return null/empty string

Returns:
String with ExtensionMobility User login name
Throws:
javax.telephony.InvalidStateException - if CiscoTerminal.getState() is not IN_SERVICE.