com.cisco.jtapi.extensions
Interface CiscoProvider

All Superinterfaces:
CiscoObjectContainer, javax.telephony.Provider

public interface CiscoProvider
extends javax.telephony.Provider, CiscoObjectContainer

Introduction

The CiscoProvider interface extends the Provider interface with additional Cisco-specific capabilities.


Field Summary
 
Fields inherited from interface javax.telephony.Provider
IN_SERVICE, OUT_OF_SERVICE, SHUTDOWN
 
Method Summary
 CiscoTerminal createTerminal(java.lang.String name)
           Returns an instance of the CiscoTerminal class which corresponds to the given name.
 void deleteCall(javax.telephony.Call call)
           Deletes an un used call created by createCall().
 void deleteTerminal(CiscoTerminal terminal)
           Removes the CiscoTerminal Ojbect from providers control.
 javax.telephony.Address getAddress(java.lang.String number, java.lang.String partition)
           
 javax.telephony.Address[] getAddresses(java.lang.String number)
           
 int getAppDSCPValue()
           This method can be used by applications to get the DSCP value from the provider.
 CiscoCall getCall(CiscoRTPHandle rtpHandle)
          Returns call object with the rtpHandle associated with a specific terminal.
 CiscoCall getCall(int callleg)
           Returns CiscoCall present in provider domain.
 boolean getCallbackGuardEnabled()
           
 CiscoIntercomAddress[] getIntercomAddresses()
           Returns array of CiscoInterComAddress present in provider domain.
 CiscoMediaTerminal getMediaTerminal(java.lang.String name)
           Returns an instance of the CiscoMediaTerminal class which corresponds to the given name.
 CiscoMediaTerminal[] getMediaTerminals()
           Returns an array of CiscoMediaTerminals associated with the Provider and within the Provider's domain.
 java.lang.String getVersion()
           
 void registerFeature(int featureID)
          used to register for a particular feature for which application will get Provider events.
 void setCallbackGuardEnabled(boolean enabled)
           Enables or disables try/catch logic for observer callbacks
 void unregisterFeature(int featureID)
          used to unregister a particular feature.
 
Methods inherited from interface javax.telephony.Provider
addObserver, createCall, getAddress, getAddressCapabilities, getAddressCapabilities, getAddresses, getCallCapabilities, getCallCapabilities, getCalls, getCapabilities, getConnectionCapabilities, getConnectionCapabilities, getName, getObservers, getProviderCapabilities, getProviderCapabilities, getState, getTerminal, getTerminalCapabilities, getTerminalCapabilities, getTerminalConnectionCapabilities, getTerminalConnectionCapabilities, getTerminals, removeObserver, shutdown
 
Methods inherited from interface com.cisco.jtapi.extensions.CiscoObjectContainer
getObject, setObject
 

Method Detail

setCallbackGuardEnabled

void setCallbackGuardEnabled(boolean enabled)

Enables or disables try/catch logic for observer callbacks

In order to protect itself from application exceptions in observer callbacks, the Provider normally guards all invocations of application interfaces (e.g. observers) with the following code:

try {

observer.callStateChanged ( ... );

} catch ( Throwable t ) {
// log the exception here
}

This isolates application errors from the JTAPI implementation, allowing easier troubleshooting, since the JTAPI implementation can note the unhandled exception and continue operating. Some errors are considered non-recoverable and will be re-thrown by JTAPI, generally resulting in application exit. Such errors include ThreadDeath, OutOfMemoryError, and StackOverflowError. Applications wishing to trap errors within JTAPI threads should create a subclass of ThreadGroup and initialize JTAPI from a thread within that ThreadGroup. By overriding the ThreadGroup.uncaughtException () method, the application can be made aware of all unrecoverable errors thrown on JTAPI threads.

In some cases, JTAPI's aggressive error-catching approach may make it more difficult to troubleshoot applications within a java debugger. Microsoft Visual J++ version 6.0, for example, does not handle breakpoints within application observer callbacks properly if JTAPI catches Throwable. In such cases, JTAPI application developers may choose to disable the internal JTAPI try/catch logic.

NOTE: Disabling callback guards in this manner is only intended for use while troubleshooting applications, and never for use in production environments. By default, callback guards are always enabled.

Parameters:
enabled - if true, callback guard will be enbled; if false, callback guard will be disabled

getCallbackGuardEnabled

boolean getCallbackGuardEnabled()
Returns:
The current state of the callback guard feature

getMediaTerminals

CiscoMediaTerminal[] getMediaTerminals()
                                       throws javax.telephony.ResourceUnavailableException

Returns an array of CiscoMediaTerminals associated with the Provider and within the Provider's domain. Each CiscoMediaTerminal possesses a unique name, which is assigned to it by the JTAPI implementation. If there are no CiscoMediaTerminals associated with this Provider, then this method returns null. This array is a subset of the array returned by Provider.getTerminals().

Post-conditions:

  1. Let CiscoMediaTerminal[] terminals = this.getMediaTerminals()
  2. terminals == null or terminals.length >= 1
  3. if terminals != null, terminals is a subset of this.getTerminals ()

Returns:
An array of Terminals in the Provider's local domain.
Throws:
javax.telephony.ResourceUnavailableException - Indicates the number of media terminals present in the Provider is too great to return as a static array.

getMediaTerminal

CiscoMediaTerminal getMediaTerminal(java.lang.String name)
                                    throws javax.telephony.InvalidArgumentException

Returns an instance of the CiscoMediaTerminal class which corresponds to the given name. Each CiscoMediaTerminal has a unique name associated with it, which is assigned to it by the JTAPI implementation. If no CiscoMediaTerminal is available for the given name within the Provider's domain, this method throws the InvalidArgumentException. This CiscoMediaTerminal is contained in the arrays generated by Provider.getTerminals() and CiscoProvider.getMediaTerminals().

Pre-conditions:

  1. Let CiscoMediaTerminal terminal = this.getMediaTerminal(name);
  2. terminal is an element of this.getTerminals();
  3. terminal is an element of this.getMediaTerminals();
Post-conditions:
  1. Let CiscoMediaTerminal terminal = this.getMediaTerminal(name);
  2. terminal is an element of this.getTerminals();
  3. terminal is an element of this.getMediaTerminals();

Parameters:
name - The name of desired CiscoMediaTerminal object.
Returns:
The CiscoMediaTerminal object associated with the given name.
Throws:
javax.telephony.InvalidArgumentException - The name provided does not correspond to a name of any CiscoMediaTerminal known to the Provider or within the Provider's domain.

registerFeature

void registerFeature(int featureID)
                     throws javax.telephony.InvalidStateException,
                            javax.telephony.PrivilegeViolationException,
                            javax.telephony.InvalidArgumentException
used to register for a particular feature for which application will get Provider events. Applications should pass in the featureID of the softkey. Current supported features are listed in CiscoProvFeatureID interface

Throws:
javax.telephony.InvalidStateException
javax.telephony.PrivilegeViolationException
javax.telephony.InvalidArgumentException

unregisterFeature

void unregisterFeature(int featureID)
                       throws javax.telephony.InvalidStateException
used to unregister a particular feature. Provider events for the feature will stop after unregistering the feature

Throws:
javax.telephony.InvalidStateException

deleteCall

void deleteCall(javax.telephony.Call call)
                throws javax.telephony.InvalidStateException

Deletes an un used call created by createCall(). An exception is generated if the call is not in IDLE state or if provider is not in Provider.IN_SERVICE state. Applications may use this interface to move un used calls to INVALID state and reclaim resources alloacated to the call.

Pre-conditions:

  1. this.getState() == Provider.IN_SERVICE
  2. call.getState() == Call.IDLE

Post-conditions:

  1. call.getState() == Call.INVALID

Throws:
javax.telephony.InvalidStateException

getCall

CiscoCall getCall(CiscoRTPHandle rtpHandle)
                  throws javax.telephony.InvalidStateException
Returns call object with the rtpHandle associated with a specific terminal. This method may return null if this rtpHandle no longer associated with any call or if there was no callObserver added on the terminal at the time when CiscoCallOpenLogicalChannelEv which contained this handle is sent to applications.

Throws:
javax.telephony.InvalidStateException

getVersion

java.lang.String getVersion()
Returns:
The current version of provider running if provider is inservice otherwise it will return empty string

createTerminal

CiscoTerminal createTerminal(java.lang.String name)
                             throws javax.telephony.InvalidArgumentException,
                                    javax.telephony.InvalidStateException,
                                    javax.telephony.PrivilegeViolationException

Returns an instance of the CiscoTerminal class which corresponds to the given name. Application must have sufficient capability otherwise PreviledgeVoilationException would be thrown CiscoProvider.createTerminal().

Pre-conditions:

  1. this.getState() == Provider.IN_SERVICE
Post-conditions:
  1. Create CiscoTerminal corresponding to name.
  2. terminal is an element of this.getTerminals();

Parameters:
name - The name of desired CiscoTerminal object.
Returns:
The CiscoTerminal object associated with the given name.
Throws:
javax.telephony.InvalidArgumentException - The name provided does not correspond to a name of any CiscoMediaTerminal known to the Provider or within the Provider's domain.
javax.telephony.InvalidStateException - The provider is not inService.
PreviledgeVoilationException - The provider does not have sufficient capbilitly i.e. CiscoProviderCapabilities.canObserveAnyTerminal() returns false
javax.telephony.PrivilegeViolationException

deleteTerminal

void deleteTerminal(CiscoTerminal terminal)
                    throws javax.telephony.InvalidArgumentException,
                           javax.telephony.InvalidStateException,
                           javax.telephony.PrivilegeViolationException

Removes the CiscoTerminal Ojbect from providers control. Application must have created this terminal using Provider.createTerminal() interface otherwise PreviledgeVoilationException would be thrown. CiscoProvider.deleteTerminal().

Pre-conditions:

  1. this.getState() == Provider.IN_SERVICE
Post-conditions:
  1. CiscoTerminal Ojbect deleted from providers list of terminal.
  2. terminal is not element of this.getTerminals() any more and Addresses belonging to terminal would also be deleted.

Parameters:
terminal - The referece to the desired CiscoTerminal object to be deleted.
Throws:
javax.telephony.InvalidArgumentException - The terminal provided is not element of this.getTerminals() or termial is not provider's domain.
PreviledgeVoilationException - The terminal given in the argument is not a terminal created using Provider.createTerminal() method. Applications can delete only those terminal which are created using Provider.createTerminal() interface.
javax.telephony.InvalidStateException
javax.telephony.PrivilegeViolationException

getAppDSCPValue

int getAppDSCPValue()

This method can be used by applications to get the DSCP value from the provider. CiscoProvider.getAppDSCPValue().

Pre-conditions:

  1. this.getState() == Provider.IN_SERVICE
Post-conditions:
  1. The method will return the integer value of the DSCP value for applications set by CTI.
  2. .


getAddresses

javax.telephony.Address[] getAddresses(java.lang.String number)
Returns:
An array of address objects corresponding to the number that is passed in the method. The address objects will be having different partitions.

getAddress

javax.telephony.Address getAddress(java.lang.String number,
                                   java.lang.String partition)
                                   throws javax.telephony.InvalidArgumentException
Returns:
An address object corresponding to the number and partition that is passed in the method. The address object will be unique for a particular number,partition combination.
Throws:
javax.telephony.InvalidArgumentException

getIntercomAddresses

CiscoIntercomAddress[] getIntercomAddresses()

Returns array of CiscoInterComAddress present in provider domain.

If there is no intercom address address configured on any of the terminal in provider domain, it will retrun null.

Returns:
CiscoIntercomAddress array

getCall

CiscoCall getCall(int callleg)

Returns CiscoCall present in provider domain.

If there is no call on any of the terminal in provider domain, with this call leg, null is returned.

Returns:
CiscoCall