ESFramework開(kāi)發(fā)手冊(cè)-Android版資料

ESFramework開(kāi)發(fā)手冊(cè)--Android版

ESFramework的Android客戶端引擎的相關(guān)API與PC版保持一致的，所以，如果熟

悉PC版的API,那么上手AndroidAPI就很容易了。

第一章發(fā)送和處理消息

使用通信框架最基礎(chǔ)的需求就是收發(fā)信息,ESFramework(Android)底層已經(jīng)為我們封裝好

了所有與信息收發(fā)相關(guān)的操作,我們只要使用<municate.framework>

下IBasicOutter接口中相關(guān)組件的API來(lái)發(fā)送信息，以及實(shí)現(xiàn)

<municate.framework>TICustomizeHandler接口來(lái)處理收到的

信息就可以了。

L客戶端發(fā)送信息

客戶端可以發(fā)送信息給服務(wù)端，也可以發(fā)送信息給其他在線用戶。

客戶端可以使用RapidPassiveEngine中的getCustomizeOutter。方法獲取

ICustomizeOutter接口的實(shí)例，通過(guò)調(diào)用實(shí)例的方法來(lái)發(fā)送信息,【CustomizeOutter具體

接口定義如下：

*向服務(wù)器發(fā)送信息。

?QparaminformationType自定義信息類(lèi)型

*@paraminfo信息

*/

voidsenddntinformationType,byte[]info）；

*向在線用戶cargecUser工選送信息。

*?paramtargetUserlD接收消息的目標(biāo)用戶工D

*?paraminformationType自定義信息類(lèi)型

*@paraminfo信息

*/

voidsend(StringtargetUserlD,intinformationType,byte[]info)；

/**

?向服務(wù)器提交請(qǐng)求信息，并返回服務(wù)器的應(yīng)答信息。如果超時(shí)沒(méi)有應(yīng)答則將拋出Timeou用常。

*SparaminformationType自定義請(qǐng)求信息的類(lèi)型

*@paraminfo請(qǐng)求信息

??return服勞器的應(yīng)音信息

*/

byte[]query(intinformationType,byte[]info);

/**

?向在線用戶或服務(wù)器發(fā)送信息。

*@paramtargetUserlD接收消息的目標(biāo)用戶工D。如果為null，表示接收者為服務(wù)■器。

*QparaminformationType自定義信息類(lèi)型

*@paraminfo信息內(nèi)容

*@parampost是否采用Pcsc模式發(fā)送消息

*?paramaction當(dāng)通道繁忙時(shí)所采取的動(dòng)作

veldsendStringtargetUserlD,intinformationType,byte[]info?booleanpest,Action!iTeOnChannells

*向在線用戶或服務(wù)器發(fā)送信息，并等待其&CX。當(dāng)前調(diào)用線程會(huì)一直阻塞，直到收到二二七如果超時(shí)都沒(méi)有收到NCX，則將拋1

*QparamtargetUserlD接收消息的目標(biāo)用戶工D。如果為null，表示信息接收者為服務(wù)端。

*GparaminformationType自定義信息類(lèi)型

*@paraminfo信息

?/

voidsendCertainly(StringtargetUserlD,intinformationType,byte[]info);

*向在線用戶或服務(wù)器發(fā)送大的數(shù)據(jù)塊信息。直到數(shù)據(jù)發(fā)送完畢，該方法才會(huì)返回。如果擔(dān)心長(zhǎng)時(shí)間阻塞調(diào)用線程，可考慮異2

*?paramtargetUserlD接收消息的目標(biāo)用戶工D。如果為null，表示接收者為服務(wù)器。

*?paraminformationType自定義信息類(lèi)型

*?parambloblnfc大的數(shù)據(jù)塊信息

*?paramfragmentSize分片傳遞時(shí)，片段的大小

*/

voidsendBlob(StringtargetUserlD?intinformationType,byte[]blobinfo,intfragmentSize)；

*向在線目標(biāo)用戶或服務(wù)器提交請(qǐng)求信息，并返回應(yīng)答信息。如果目標(biāo)用戶不在線，或超時(shí)沒(méi)有應(yīng)答則將拋出TimeoutE

*@paramtargetUserlD接收并處理請(qǐng)求消息的目標(biāo)用戶工D。如果為null，表示信息接收者為服務(wù)■端。

*@paraminformationType自定義請(qǐng)求信息的類(lèi)型

*@paraminfo請(qǐng)求信息

*0return應(yīng)答信息

*/

byte[]query(StringtargetUserlD,intinformationType,byte[]info)；

*回復(fù)異步調(diào)用。向在線目標(biāo)用戶或服務(wù)器提交請(qǐng)求信息，當(dāng)收到應(yīng)答信息或超時(shí)時(shí)，將回調(diào)KllbackHandlerg數(shù)。

*@paramtargetUserlD接收并處理請(qǐng)求消息的目標(biāo)用戶ID。如果為null，表示信息接收者為服務(wù)端。

*@paraminformationType自定義請(qǐng)求信息的類(lèi)型

*@paraminfc請(qǐng)求信息

*@paramhandler用于處理回復(fù)信息的處理器

*@paramtag攜帶的狀態(tài)數(shù)據(jù)，將被傳遞給回調(diào)函數(shù)handler

*/

voidqueryStringtargetUserlD/intinformationType,byte口info,CallbackHandlerhandler.Objecttag);

發(fā)送消息有幾種方式

普通發(fā)送:

調(diào)用send(StringtargetUserlD,intinformationType,byte口info)方法進(jìn)行普通發(fā)

送，即將信息寫(xiě)入網(wǎng)絡(luò)流后就立即返回。

send方法的重載有個(gè)ActionTypeOnChannellsBusy參數(shù),用于指示當(dāng)通道繁忙時(shí)所

采取的動(dòng)作：繼續(xù)發(fā)送、或丟棄數(shù)據(jù)。在某些系統(tǒng)中,對(duì)于一些非重要非緊急信息的發(fā)送，

可以為ActionTypeOnChannellsBusy參數(shù)傳入枚舉值Discard(丟棄)。

帶ACK機(jī)制的發(fā)送：

調(diào)用sendCertainly方法發(fā)送信息時(shí)會(huì)啟用ACK機(jī)制，即將信息發(fā)送出去后，調(diào)用并

不返回，而是要等到接收方的ACK后，才返回。ACK機(jī)制是由ESPIus底層實(shí)現(xiàn)的，我們

直接使用，不需要做件可額外的其它工作。關(guān)于帶ACK機(jī)制的信息發(fā)送的更多內(nèi)容可以參

見(jiàn)ACK機(jī)制。

信息同步調(diào)用：

調(diào)用query(intinformationType,byte[]info)和query(String

targetUserlD,intinformationType,byte[]info)方法可以發(fā)送請(qǐng)求信息,并返回接收方

處理請(qǐng)求后的應(yīng)答信息。就像方法調(diào)用一樣--使用參數(shù)調(diào)用方法并返回結(jié)果。從兩個(gè)

query方法的重載看到，信息同步調(diào)用的對(duì)象既可以是服務(wù)端、也可以是另外一個(gè)在線客戶

端。關(guān)于信息同步調(diào)用的更多內(nèi)容可以參見(jiàn)消息同步調(diào)用。

回復(fù)異步調(diào)用：

重載的voidquery(StringtargetUserlD,intinformationType,byte[]info,

CallbackHandlerhandler,Objecttag)方法，在發(fā)送請(qǐng)求信息后,不會(huì)阻塞而繼續(xù)向下執(zhí)行,

而框架在收到對(duì)應(yīng)的回復(fù)信息時(shí)，會(huì)調(diào)用CallbackHandler的execute方法體。由于調(diào)用

線程與回復(fù)回調(diào)的線程不是同一個(gè)線程，所以稱這種機(jī)制為回復(fù)異步調(diào)用。

發(fā)送達(dá)數(shù)據(jù)塊:

調(diào)用sendBlob方法可以將大數(shù)據(jù)塊信息發(fā)送給服務(wù)端或任何其他的在線用戶。

2.處理信息

客戶端可以收到來(lái)自其它客戶端或服務(wù)端的信息、大數(shù)據(jù)塊、以及同步調(diào)用。服務(wù)端

也可以收到來(lái)自客戶端的信息（轉(zhuǎn)發(fā)的信息除外）及同步調(diào)用。那么，我們?nèi)绾翁幚磉@些接

收到的信息了？無(wú)論是8艮務(wù)端，還是客戶端，都只要實(shí)現(xiàn)ICustomizeHandler接口即可。

*自定義消息處理器

*@authordaixun

publicinterfacelCustcmizeMandler{

*處理來(lái)自其他用戶的信息（包括大數(shù)據(jù)塊信息）。

*@paramsourceUserlD發(fā)出信息的用戶工D。如果為null，表示信息來(lái)自服務(wù)■瑞。

*@paraminformationType自定義信息類(lèi)型

*@paraminfo信息

*/

voidhandleinformation（StringsourceUserlD^intinformationType,byte[]info）；

*處理來(lái)自其它在線用戶的F2喃求并返回應(yīng)答信息。

*SparamsourceUserlD發(fā)送清求信息的用戶工D。如果為null，表六信息來(lái)自服務(wù)端。

*SparaminformationType自定義請(qǐng)求信息的類(lèi)型

*QparaminfoP2耳青求信息

*0returnP2F應(yīng)答信息

byte[]handleQuery(StringsourceUserlD,intinformationType,byte[]info);

)

接口說(shuō)明

(1)在實(shí)現(xiàn)這個(gè)接口之后，只需要實(shí)例化這個(gè)具體的實(shí)現(xiàn)類(lèi)，并在RapidPassiveEngine

的customizeHandler屬性即可自動(dòng)處理接收到的消息

(2)凡是sourceUserlD參數(shù)為null的，都表示被處理的信息是來(lái)目服務(wù)端的；否則，表

示被處理的信息是由其它在線客戶端發(fā)出的。

(3"CustomizeHandler接口的所有方法都是在后臺(tái)線程中被調(diào)用的，所以如果這些方法

的實(shí)現(xiàn)中不能直接修改UI線程

(4)在客戶端，可以將ICustomizeHandler的實(shí)現(xiàn)類(lèi)的實(shí)例傳遞給RapidPassiveEngine

的initialize方法以掛接到框架。

3.更多說(shuō)明

信息發(fā)送模型

信息發(fā)送可以使用同步模型或異步模型，在方法中通過(guò)bool型post參數(shù)體現(xiàn)出來(lái)。

如果其值為true,表示使用異步模型(即發(fā)送方法的調(diào)用立即返回，不用等到信息發(fā)送完

畢)；否則使用同步模型(阻塞調(diào)用線程，直到信息發(fā)送完畢)。

信息處理

客戶端和服務(wù)端的ICustomizeHandler,我們稱之為自定義信息處理器，或者業(yè)務(wù)處

理器，表示其用于處理我們應(yīng)用系統(tǒng)的具體業(yè)務(wù)邏輯。

(1)業(yè)務(wù)處理器將在后臺(tái)線程中被調(diào)用，所以，實(shí)現(xiàn)業(yè)務(wù)處理器的方法中如果涉及到了

UI操作，則必須將調(diào)用轉(zhuǎn)發(fā)到UI線程。

(2)業(yè)務(wù)處理器的方法必須盡可能快地返回，否則，將不能及時(shí)地處理后續(xù)的消息。如果

某個(gè)業(yè)務(wù)處理方法非常耗時(shí)，可以考慮使用異步方式。

大數(shù)據(jù)塊

當(dāng)發(fā)送大數(shù)據(jù)塊時(shí)，發(fā)送方會(huì)將其拆分為許多連續(xù)的片段逐個(gè)發(fā)送，而在接收方會(huì)自動(dòng)

將接收到的片段重組起來(lái)構(gòu)成一個(gè)完整的信息。而且無(wú)論是發(fā)送大數(shù)據(jù)塊，還是普通信息,

在接收方都是調(diào)用相同的方法(ICustomizeHandler的handleinformation方法)來(lái)處理

的。

第二章好友與組

IFriendOutter和IGroupOutter的或能已被IContactsOutter模塊所取代

第三章聯(lián)系人

聯(lián)系人(IContactsOutter)是ESFramework6.0(必須與對(duì)應(yīng)版本的服務(wù)端配合使用)新增的

功能，此接口將之前的好友與組功能進(jìn)行整合，并取而代之

*用干客戶湍發(fā)送與聯(lián)系人操作相關(guān)的信息和廣悟。

//

publicinterfaceIContactsOutter{

/*★

*獲取所有在線的聯(lián)系人。

*

*/

Li3t<String>getAllOnlineContacts();

/**

*獲取聯(lián)系人列表。

.

*/

List<String>getContacts();;

/**

*獲取組的成員。

*QparamgroupID接收廣播信息的組ID

*/

GrcupMatesgetGrcupMembers(StringgroupID);;

/**

*獲取聯(lián)系人列表。

*SparamgroupID接收廣播信息的組工D

*?parambroadcastlype廣播信息的類(lèi)型

*Gparambroadcastcontent信息的內(nèi)容

*@paramaction當(dāng)通道繁忙時(shí)采取的操作

*/

voidbroadcast(StringgroupID,intbroadcascType,byte[]broadcastcontent,AccionTypeC

voidsetCcntactsEventListener(ContactsEventListenereventListener);

}

*聯(lián)系入監(jiān)聽(tīng)接口

publicinterfaceContactsEv^entListener{

當(dāng)聯(lián)系人上線時(shí)，觸發(fā)此事件。

@paramuserID好友的工D

voidcontactsCcnnected(StringuserID);

*當(dāng)聯(lián)系人下線時(shí)，觸發(fā)此事件。

*@paramuserID好友的U§er1D

voidcontacrsOffline(StringuserID);

/**接收群組消息

*@parambroadca3X；erID

*@paramgroupID

*[parambroadcastType

*?parambroadcastcontent

voidbroadcastReceived(StringbrcadcasterlD,StringgrcupID,intbrcadcastlype,byte[]b:

)

1.接口說(shuō)明

(1)getGroupMembers會(huì)返回某個(gè)組的所有成員，并將在線成員與不在線成員區(qū)分開(kāi)

來(lái)。

(2)當(dāng)用戶上線或下線時(shí)，框架會(huì)回調(diào)ContactsEventListener接口的

contactsConnected或contactsOffline事件以通知其所有相關(guān)聯(lián)系人。

(3)可以通過(guò)Broadcast向任何一個(gè)組發(fā)送廣播,目標(biāo)組的每個(gè)在線成員都將會(huì)通過(guò)

ContactsEventListener的BroadcastReceived事件來(lái)獲得廣播內(nèi)容。

2.關(guān)注聯(lián)系人的實(shí)時(shí)狀態(tài)

在類(lèi)似IM的系統(tǒng)中，每個(gè)運(yùn)行的客戶端實(shí)例，在其運(yùn)行的整個(gè)生命周期中，都需要清楚

地知道與其相關(guān)每個(gè)聯(lián)系人的實(shí)時(shí)狀態(tài)，這個(gè)需求可以這樣來(lái)實(shí)現(xiàn)：

(1)當(dāng)某個(gè)客戶端登陸成功后，就調(diào)用getContacts方法和getAIIOnlineContacts方法

以獲取聯(lián)系人列表和所有的在線聯(lián)系人列表。這樣，就知道了所有聯(lián)系人的初始狀態(tài)。

(2)實(shí)現(xiàn)ContactsEventListener事件接口,并通過(guò)setContactsEventListener方法預(yù)

定事件,然后在運(yùn)行的過(guò)程中，當(dāng)contactsConnected和contactsOffline事件觸發(fā)時(shí)，

就修改對(duì)應(yīng)聯(lián)系人的狀態(tài)。這樣就保證我們的客戶端可以實(shí)時(shí)地知道每個(gè)相關(guān)的聯(lián)系人是否

院

第四章在線用戶管理、基礎(chǔ)功能及狀態(tài)通知

本文介紹ESFramework開(kāi)發(fā)手冊(cè)(00)??概述一文中提到的四大武器的第二個(gè):在

線用戶管理、基礎(chǔ)功能及狀態(tài)通知。

在解決了發(fā)送信息和處理信息之后,還有一些基礎(chǔ)功能是很多分布式通信系統(tǒng)都需要用

到的，比如，查洵某個(gè)用戶是否在線、獲取在線用戶列表、自己掉線時(shí)得到通知，等等.

IBasicOutter下的組件，為我們解決了這些基礎(chǔ)問(wèn)題。

1.客戶端

客戶端通過(guò)調(diào)用<municate.framework.IBasicOutter>接口對(duì)

應(yīng)的方法就可以完成基礎(chǔ)功能或得到相關(guān)狀態(tài)改變通知。我們可以

<RapidPassiveEngine>K)getBasicOutter。方法來(lái)獲取IBasicOutter引甩

publicinterfaceIBasicOutcer{

booleanislnitializedf);

/**

*當(dāng)自己被同名用戶擠掉線時(shí)，觸發(fā)此事件。此時(shí)，客戶端弓I擎已被Dispose。

*/

voidbeingPushedOut();

/**

*當(dāng)自己被服務(wù)端踢出掉線時(shí)，觸發(fā)此事件。此時(shí)，客戶端引擎已被Dispose。

*/

voidbeingKickedOut();

/**

*客戶端登陸始證。工RapidPassiveEngine會(huì)在初始化時(shí)，自動(dòng)調(diào)用該方法來(lái)蛉證用戶賬號(hào)密碼。

*Qparamsystemloken系統(tǒng)標(biāo)志。用于蛉證客戶端是否與服務(wù)端屬于同一系統(tǒng)。

*@parampassword登陸擊碼

*@return

ReapLogonlogon(StringsystemTcken,Stringpassword);

/★*

*獲取自己的工PE。

*Sreturn通常是經(jīng)過(guò)N2T之后的工PE

*/

AgilelPEgetMylPEO；

/**

*獲取當(dāng)前*5上的斫有在線的用戶列表?！驹摲椒▋H僅用于deme和測(cè)試】

*@return

List<String>getAHOnlineUsers();

*查詢用戶是否在線。

*@paramuserID用戶id

*@return

*/

booleaniaUserOnline(StringuserID);

*ping服務(wù)■器。在應(yīng)用層模擬ping，比普通的工CM唯Ipin求一些(如"10ms)。

*Qreturnping耗時(shí)，單位塞秒

*/

intping();

*Ping其他在線用戶(通過(guò)月艮務(wù)翳中轉(zhuǎn))。

*如果目標(biāo)用戶不在線，將拋出limeou得常。

*@paramtargetUserlD要Pin*)目標(biāo)用戶工D

*@returnping耗時(shí)，單位塞秒

*/

intping(StringtargetUserlD);

*命令服務(wù)端將目標(biāo)用戶踢出。如果目標(biāo)用戶不在當(dāng)前&S上，則直接返回。

*@paramtargetUserir要踢出的用戶工D

*/

voidkickOut(StringtargerUserlD);

*向服務(wù)器發(fā)送心跳消息。被框架ESFramework.Android.Application.Basic.Passive使用)

*/

voidsendHeartBeatMessage();

狀態(tài)改變事件通知

首先，我們看看RapidPassiveEngine暴露的兩個(gè)事件：

1.beingKickedOut當(dāng)自己被踢出時(shí)將觸發(fā)該事件。

2.beingPushedOut發(fā)生于當(dāng)服務(wù)端將重登陸模式設(shè)置為ReplaceOld時(shí)，并且同名

用戶的成功登錄，將會(huì)把老的在線用戶擠掉而導(dǎo)致其下線。關(guān)于重登陸模式的更多

內(nèi)容可以參見(jiàn)重登陸模式.

基礎(chǔ)API

接下來(lái)，我們簡(jiǎn)單看看BasicOutter的幾個(gè)方法。

1.logon方法用于在登錄時(shí)驗(yàn)證用戶密碼。該方法會(huì)在客戶端Rapid引擎初始化時(shí)被

引擎自動(dòng)調(diào)用，所以，在使用Rapid引擎時(shí)，我們通常不需要手動(dòng)調(diào)用它。如果有

的系統(tǒng)需要驗(yàn)證除了密碼之外更多的信息,那么可以通過(guò)systemToken參數(shù)進(jìn)行

傳遞這些額夕MS息。Logon方法返回類(lèi)型為L(zhǎng)ogonResponse其屬性LogonResult

表示了登錄結(jié)果。如果LogonResult為0表示登錄成功如果LogonResult為2,

表示該賬號(hào)已經(jīng)在其它地方音錄；如果LogonResult為1,則表示驗(yàn)證賬號(hào)密碼沒(méi)

有通過(guò)，沒(méi)有通過(guò)的原因由LogonResponse的FailureCause屬性指明。

1.getAIIOnlineUsers用于獲取所有在線用戶，通常該方法僅僅用于dem。，因?yàn)樵?/p>

正式的系統(tǒng)中，在線用戶數(shù)可能是非常巨大的，這將導(dǎo)致GetAIIOnlineUsers的返

回消息非常大，甚至可能超過(guò)框架的最大消息尺寸的限制。

2.ping系列方法，用于獲取當(dāng)前客戶端到服務(wù)端或到另一個(gè)在線客戶端的消息來(lái)回的

耗時(shí)，由于其是在應(yīng)用層來(lái)模擬類(lèi)似ICMP的ping,所以這個(gè)方法返回的值通常比

ICMP的ping人一些。盡管如此，在一些應(yīng)用中，該P(yáng)ing的結(jié)果還是有一些參考

價(jià)值的。

3.有時(shí)，我們需要命令服務(wù)器將一些惡意的用戶從服務(wù)端踢出（斷開(kāi)其連接），那么

就可以調(diào)用kickOut方法，被踢出的客戶端將會(huì)觸發(fā)上述的beingKickedOut事

件。

4.sendHeartBeatMessage方法用于向服務(wù)器發(fā)送心跳消息。如果我們使用的是

Rapid引擎，那么框架會(huì)自動(dòng)發(fā)送心跳消息，所以，我們通常不需要手動(dòng)調(diào)用該方

法。關(guān)于心跳消息的更多內(nèi)容可以參見(jiàn)心跳機(jī)制。

TCP連接狀態(tài)

<municate.framework.IBasicOutter>提供了一分基礎(chǔ)功能,還有

另一部分很重要的基礎(chǔ)功能需要涉及到客戶端的Rapid引擎我們?cè)谶@里也一并介紹一下。

客戶端如何知道自己與服務(wù)器的TCP連接的狀態(tài)及其變化了？

municataframework.IRapidPassiveEngine）的幾個(gè)事件來(lái)獲取這

些信息。

*當(dāng)客戶湍與服務(wù)器的工行連接斷開(kāi)時(shí)，將觸發(fā)此事件。

voidconnectionlnterruptedO;

*當(dāng)客戶端與服務(wù)端的TCF連搔建立時(shí)會(huì)觸發(fā)此事件

voidconnectionRebuildStart();

?當(dāng)斷線重連開(kāi)始時(shí)會(huì)觸發(fā)此事件

*/

voidrelogin3egin();

*當(dāng)斷線重連成功時(shí)，會(huì)自動(dòng)登錄服務(wù)器始證用戶賬號(hào)密碼，并觸發(fā)此事件。如果蛉證失敗，則與服芬器的連接符會(huì)斷牙

?事件參數(shù)表明了登錄蛉證的結(jié)果。

voidrelogonCompleted(RespLogonresult);

*返回當(dāng)前引擎所連接的服務(wù)器的地址。

*?return

Agile工PEgetServerAddress(