Csico JTAPI Developer Guide 7.0 读书笔记(1)

Jtapi 是sun为了解决pc上的电话通讯和设备提供商共同开发的一套应用程序接口。

Csico JTAPI 就是在JTAPI 1.2版本基础上进行的扩展，更好的兼容Csico IP电话产品。

 

主要应用在：控制和监测 CUCM 上的电话。cti和虚拟设备间的路由调用。

 

jatpi 与cc

  jtapi在呼叫中心上监控设备的状态，进行呼叫控制，自动脚本，远程呼叫。

 

jtapi的工作流程：

1.通过JTAPIPeerFactory获得一个JTAPIPeer 对象实例
2.使用JTAPIPeer对象的getProvider()方法获得一个Provider对象
3.应用程序使用的Terminal和Address对象都是从Pervider对象中获得的。
4.确定相关对象的作用。
5.在应用程序需要监控和控制的对象上添加observers。
6.开始应用程序流程。

Jtprefs APP

 

cisco jtapi tools 自带的应用程序，配置Csico Unified JTAPI参数。

 

Cisco Unified JTAPI 概念：

 

  CisocObjectContainer Interface

对象容器接口允许app关联app-定义的对象和实现对象的接口，在cu jtapi中的扩展接口如下：
CiscoJTAPIPeer
CiscoProvider
CiscoCall
CiscoAddress
CiscoTerminal
CiscoConnection
CiscoTerminalConnection
CiscoConnectionID
CiscoCallID

Provider 是通过实现JtapiPeer对象来创建的，起到了连接app和jtapi实现的主要作用，
Provider对象是一个包括了全部呼叫模式对象的集合，包括：Address，Terminals和Calls，app可以随时控制这些对象。

 

Provider 的初始化和关闭

调用JtapiPeer.getProvider(“CTIManagerHostname;login=user;passwd=userpassword;appinfo=CiscoSoftphone”)获得Provider，

hostname：cucm的ip地址

user：赋予控制设备权限的用户

appinfo:可选

 

 初始化：当获得一个Privoder对象后即与CUCM建立了TCP连接，实现了与cucm的握手，完成了设备列表列举。这是Provider处于 OUT_OF_SERVICE状态，japi程序只有等到受控设备通过验证后，才能变成IN_SERVICE状态，ProvInServiceEv 事件传递一个实现了ProviderObserver接口的对象。必须调用provider.addOberver()将observer添加到provider上.App必须等待Provider处于service的通知。

 

关闭：调用provider.shutdown()关闭（ProvShutdownEv 事件）

 

 Provider.getTerminals()：返回当前用户在cucm中由admin赋予控制的终端设备列表

Provider.getAddresses()：返回当前用户控制的线路上的电话号码数组

获得Terminal和Address对象后都需要调用addObserver

 

Address and Terminal Relationships

Address可以看成一个电话号码，Terminal可以看成一个电话。一个Terminal上可以有一个或多个Address。一个Address也可以关联到多个Terminal

 

Unobserved Addresses and Terminals

只有在CallOberver关联到provider对象上的addresses 和 terminals后jtapi才能进行打电话。 通过Call.connect()方法实现一次通话，系统也必须将CallObserver添加到addresses 和 terminals

 

Connection

一个Connection是对Call(getCall())和Address(getAddress)之间的通讯连接的抽象。通过对Connection Object的属性查看，可以分析出当前Call Object与Address Object的连接状态信息。Connection Object的状态有IDLE、ACTIVE、RINGING、DROPPED等等。

 

Terminal Connections

是表示terminal和connections的持续连接。一个Terminal Connections引用是call事件调用terminal(getTerminal())和connection(getConnection()).

 

Terminal and Address Restrictions

 管理员可以限制Terminal和Address，例如像设置黑名单一样。Jtapi也可以和限制这个设备。通过验证接口调用CiscoTerminal.isRestricted()方法和CiscoAddress.isRestricted(Terminal)，检查是否被限制。对于分享线路，应用程序可以调用CiscoAddress.getRestrictedAddrTerminals()验证一个address在terminal上是否被限制。

如果一个线路或设备被禁用，则应用程序启动后，将会视为CiscoAddrRestrictedEv，CiscoTermRestrictedEv

如果线路或设备有任何的observers，app将会视为(will see)CiscoAddrOutOfService，CiscoTermOutOfService

如果一个线路从限制列表中删除了，则app将视为CiscoAddrActivatedEv，CiscoTermActivatedEv

如果线路有任何的observer，则app看成CiscoAddrInServiceEv

如果一个设备被禁止则在上面的所有线路视为CiscoAddrRestrictedEv

如果app试图在一个受限制的线路或设备上添加一个监测怎会抛出一个PlatformException错误。

如果设备在添加了observer以后被设为受限时，app不能获得这个observer发出的事件，除非解除限制，app也可以选择取消线路或设备上的observer。

 

 一个分享线路受限，app视为CiscoAddrRestrictedOnTerminalEv。

如果address上存在监视器，app将视这个terminal为CiscoAddrOutOfServiceEv

当所有的分享线路被加载到受限列表中，则当最后一个被加入的时候，app视为CiscoAddrRestrictedEv

如果分享线路解除限制后，app视为CiscoAddrActivatedOnTerminalEv

如果address上有监视器，app视这个设备为CiscoAddrInServiceEv

如果分享线路上所有的线路都解除了限制，则这个设备商的地址的状态返回到InService事件。

 

如果所有的分享线路从控制列表加入到受限列表中后，app试图添加observers，将抛出异常。

如果有部分在受限列时，在非受限address上添加observer则条线路是in service。

 

如果正在通话中的连接，当address或terminal受到限制或重启，则app将connection和TerminalConnection断开连接。

 

下面列出了当address和terminal受限制时的状态

 

boolean CiscoTerminal.isRestricted()

判断这个设备是否受限，受限制则这个设备商分配的又有线路都将受到限制。返回true受限，false不受限。

 

javax.telephony.Terminal[] CiscoAddress.getRestrictedAddrTerminals()

返回受限制线路上的设备列表，如果没有受限制的，则返回null。

在分享线路上，设备上可能有一些线路受限。这个方法返回这个指定受限线路上的所有terminals。app不能获得受限线路的事件，如果一个受限线路在一个通话中的。一个外部连接创建到受限制线路上。

 

boolean CiscoAddress.isRestricted(javax.telephone.Terminal terminal)

这个设备上有受限制线路，则为true，否则为false

 

public interface CiscoRestrictedEv extends CiscoProvEv {
public static final int ID = com.cisco.jtapi.CiscoEventID.CiscoRestrictedEv;
/**
* The following define the cause codes for restricted events
*/
public final static int CAUSE_USER_RESTRICTED = 1;
public final static int CAUSE_UNSUPPORTED_PROTOCOL = 2;
}

受限制描述，1：terminal或address被置为受限制； 2：cujtapi不支持的设备如：7960、7940的SIP服务时。

 

 CiscoAddrRestrictedEv

 

CiscoRestrictedEv 继承自 CiscoAddRestrictedEv 接口。应用程序当cucma设定了一个线路或一个设备被指定为受限制的，获得这个事件。受限制的线路，地址不在服务状态，知道再次接通后在服务状态。如果一个地址受限制，addCallObsserver和addObserver将抛出一个异常。对于分享线路，如果有一部分的分享线路被限制，其他的线路不会受到限制，但是受限的分享线路不会返回任何时间。在添加observer之前，如果地址收到限制，app将视为CiscoAddrOutOfServiceEv，当地址是可连通，address将in service。

 

CiscoAddrRestrictedOnTerminalEv

CiscoAddrRestrictedOnTerminalEv继承自CiscoAddrRestrictedOnTerminalEv.如果一个用户有一个分享地址在控制列表中，或者如果一个线路被加载到受限制类表中，将触发这个事件。getTerminal()接口返回受限制地址的设备。接口getAddress()返回受限制的地址。

javax.telephony.Address getAddress()
javax.telephony.Terminal getTerminal()

 

CiscoAddrActivateOnTerminal

CiscoAddrActivateOnTerminal继承自CiscoProvEv。当一个分享线路或一个设备解除限制，将触发这个事件。接口getTerminal()返回被添加地址的设备。接口getAddress()返回添加到设备上的地址。

javax.telephony.Address getAddress()
javax.telephony.Terminal getTerminal()

 

CiscoTermRestrictedEv

CiscoTermRestrictedEv继承自CiscoRestrictedEv。当一个设备受到限制触发获得这个事件。app不会获得这个设备或设备上受限制的address的事件。如果设备在InService状态时受到限制，app将获得这个事件，设备或相关的地址将变为out-of-service状态。

 

 CiscoTermActivateEv

 

 CiscoTermActivateEv继承自CiscoRestrictedEv。

javax.telephony.Terminal getTermina() 返回处于活动或解除限制的列表。

 

CiscoOutOfServiceEV

static int CAUSE_DEVICE_RESTRICTED
一个设备受到限制时是否发送了事件。
static int CAUSE_LINE_RESTRICTED
标示是否有线路被限制发送事件。

 

CiscoCallEv

 

 

static int CAUSE_DEVICE_RESTRICTED
Indicates whether an event is sent because a device is restricted.
static int CAUSE_LINE_RESTRICTED
Indicates whether an event is sent because a line is restricted.

 

CsicoConnectionID

描述了被关联到Cisco Unified JTPAI 每一个连接的唯一对象。在app中可能使用对象自己或一个整数描述这个对象。

 

 

Querying Dynamic Objects

最好不要查询动态对象如call对象。到获得事件位置，可以会有不同的状态。例如，当你获得一个CiscoTransferStartEv为止，转换call可能已经取消了所有的内部连接。