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

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

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

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

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

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

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

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

信息就可以了。

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

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

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

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

接口定義如下：

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

*?paraminformationTipe自定義信息類型

*?paraminfo信息

*/

voidsend(intinformationType?byte[infc)；

*向在線用戶caigecUserl二發(fā)送信息。

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

*GparaminfonnaLionlipe自定義信息類型

*?paraminfo信息

*/

voidsendGtringtargetUserlD,intinformationType,byte[info)；

/**

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

*?paraminformationTipe自定義請(qǐng)求信息的類型

*Gparaminfo請(qǐng)求信息

*?return服務(wù)器的應(yīng)答信息

*/

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

/**

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

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

*?paraminformation!ipe自定義信息類型

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

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

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

voidsend(StringtargetUserlD,intinformationType,bvte[]info.booleanpest,Action!iTe2nChannells

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

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

*?paraminfcrmationl^e自定義信息類型

*@paraminfo信息

*/

vcidsendCertainly(StringtargetUserlD,intinfomationType,byte[]info);

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

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

*?paraminfcrmationise自定義信息類型

*?paramblobinfo大供徽據(jù)塊信息

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

*/

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

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

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

*@paraminfcrmacionT/pe自定義請(qǐng)求信息的類型

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

*Qreturn應(yīng)答信息

*/

kyte[]queryStringtargetUserlD,intinformationType,fcvre[1info)；

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

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

*@paramin工crmacionT/pe自定義請(qǐng)求信息的類型

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

*Gparamhandler用于梵理回復(fù)信息的處理器

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

*/

VCidqueryStringtargetiJserlD,intinformationType,fc;rte[]info,CallbackHandlerhandler.Objecttag);

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

普通發(fā)送:

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

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

發(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ú)論是B艮務(wù)端，還是客戶端，都只要實(shí)現(xiàn)ICustomizeHandler接口即可。

/**

*自定義消息處理器

*@authordaixun

publicinterfscelCustoinizeHandler{

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

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

?@paraminformationT^e自定義信息類型

?@paraminfo信息

?/

VCidhandleinformationfiringsourceUserlD,intinformationType,fcyte[info）；

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

*?paramsourceUserlD發(fā)送請(qǐng)求信息的用戶工D。如果為null，表示信息來(lái)自服務(wù)端。

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

*?paraminfoP2E請(qǐng)求信息

*QreturnP2F應(yīng)答信息

*/

Cvte[]handleQueryStringsourceUserlD,intinformationType,byte[]info）；

）

接口說(shuō)明

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

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

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

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

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

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

(4)在客戶端，可以將ICustomizeHandler的實(shí)現(xiàn)類的實(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)處理

的。

第二章好友與組

IFriendOuttei?和IGroupOutter的功能已被IContactsOutter模塊所取代

第三章聯(lián)系人

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

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

/**

“用于客戶端發(fā)送與聯(lián)系人操作相關(guān)的信息和廣播。

publicinterfaceICcntactsOutter{

/**

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

*

*/

Li3t<String>getAllOnlineScntacts();

/**

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

*

*/

List<String>getContacts();;

/**

*獲取組的成員。

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

*/

GrcupMatesgetGrcupMer^ers(StringgrcupID);;

/**

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

*@paramgrcupID接收廣播信息的組ID

*Sparambrcadcasclype廣播信息的類型

*@parambrcadcastContent信息的內(nèi)容

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

*/

voidbrcadcsst(StringgroupID,intbrcadcastTi^pe,byte[]brcadcsstCcntent,Actionl^eC

voidaeLCcnLdCCsEventLlscener(ConcdCLsflvenLListenerevencListener);

)

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

publicinterfaceCcntact3E\'entLi3tener{

/**

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

*@paramuserID好友的工D

*/

voidccntactsCcnnected(StringuserID);

/**

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

*@paramuserID好友的UserID

?/

voidccntactsOzfline(StringuserID);

/??接收群組消息

*@parambroadcasterlD

*0paramgroup工D

*?parambroadcascType

*?parambroadcastcontent

*/

voidbrcadcastReceived(StringbroadcasterlD,StringgroupID,intbrcadcastl^e,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)

在類似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)用(comQmunicate/ramework.IBasicOutter,接口對(duì)

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

<RapidPassiveEngine>B9getBasicOutter()方法來(lái)獲取IBasicOutter引用。

publicinterfaceIBasicOutLer{

booleanisInitializedO;

/**

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

*/

voidfceingPushedOuc();

/**

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

*/

voidbeingKickedCuc();

/**

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

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

*@parampassword登陸密碼

*@return

*/

ReapLcgcnicgcn(Stringsyater.Tcken,Stringpasswcrd);

/**

*獲取自己的工PE。

*0return通常是經(jīng)過(guò)HAT之后的工PE

*/

Agile工FEgetMylPEO；

/**

*獲取當(dāng)前*S上的所有在線的用戶列表。［該方法僅僅用于deme和測(cè)試】

*@return

113t<String>getAHOnlineUsers();

*查詢用戶是否在線。

*QparamuserID用戶id

*@return

*/

bccleanisUserOnline(StringuserID);

*Ping服務(wù)器。在應(yīng)用曇模手膽ing,比普通的工CM三的ping大一些(如"10ms)。

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

*/

intping();

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

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

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

*^returnping耗時(shí)，單位至秒

*/

inrping(StringtargetUserlD);

/**

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

*@paramtargetUserlD要踢出的用戶工D

*/

voidkickOur(StringrargerUserlD);

/**

*向服費(fèi)器發(fā)送心跳消息。被框架ESFramework.Android.Application.magic.Passive.Jieartmeater使用。

*/

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)行

傳遞這些額外信息。Logon方法返回類型為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用于獲取所有在線用戶，通常該方法僅僅用于demo,因?yàn)樵?/p>

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

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

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

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

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

價(jià)值的。

3.有時(shí)，我們需要命令服務(wù)器將一些惡意的用戶從服務(wù)端踢出（斷開(kāi)其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)及其變化了？

<municate.framework.IRapidPassiveEngine>的幾個(gè)事件來(lái)獲取這

些信息。

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

voidccnnectionlntsrrupted();

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

voidccnnecticnRebJildStart();

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

voidrelcgin3egin();

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

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

voidrelcgcnCcmpleced(RespLcgcnresult);

/?*

“返回當(dāng)前引擎所連接的服芬器的地址。

*0return

//

AgilelPEgetSerxTerAddre33();

//*?

*當(dāng)前是否處于連接狀態(tài)。

*@return

*/

boole