ESFramework開發手冊—Android版

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

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

第一章發送和處理消息

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

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

下IBasicOutter接口中相關組件的API來發送信息，以及實現

<municate.framework>下ICustomizeHandler接口來處理收到的

信息就可以了。

L客戶端發送信息

客戶端可以發送信息給服務端，也可以發送信息給其他在線用戶。

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

ICustomizeOutter接口的實例，通過調用實例的方法來發送信息,ICustomizeOutter具體

接口定義如下：

*向服務器發送信息。

*?paraminformationTipe自定義信息類型

*?paraminfo信息

*/

voidsend(intinformationType?byte[infc)；

*向在線用戶caigecUserl二發送信息。

*?paramtargetUserlD接收消息的目標用戶工D

*GparaminfonnaLionlipe自定義信息類型

*?paraminfo信息

*/

voidsendGtringtargetUserlD,intinformationType,byte[info)；

/**

?向服務器提交請求信息，并返回服務器的應答信息。如果超時沒有應答則將拋出：【meou號常。

*?paraminformationTipe自定義請求信息的類型

*Gparaminfo請求信息

*?return服務器的應答信息

*/

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

/**

?向在線用戶或服務器發送信息。

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

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

*?paraminfo信息內容

*@parampost是否采用Fos：模式發送消息

*@paramaction當通道繁忙時所采取的動作

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

?向在線用戶或服務器發送信息，并等待其NCL當前調用線程會一直阻塞，直到收到20X；如果超時都沒有收到&CX,則將拋1

*?paramtargetUserlD接收消息的目標用戶工D。如果為null，表示信息接收者為服務端。

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

*@paraminfo信息

*/

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

*向在線用戶或服務器發送大的數據塊信息。直到數據發送完畢，該方法才會返回。如果擔心長時間阻塞調用線程，可考慮異2

*?paramtargetUserlD接收消息的目標用戶工D。如果為null，表示接收者為服務器。

*?paraminfcrmationise自定義信息類型

*?paramblobinfo大供徽據塊信息

*?paramfragmentSize分片傳遞時，片段的大小

*/

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

*向在線目標用戶或服務器提交請求信息，并返回應答信息。如果目標用戶不在線，或超時沒有應答則將拋出工打￡心琥

*@paramtargetUserlD接收并處理請求消息的目標用戶工D。如果為null，表示信息接收者為服務端。

*@paraminfcrmacionT/pe自定義請求信息的類型

*@paraminfo請求信息

*Qreturn應答信息

*/

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

*回復異步調用。向在線目標用戶或服務器提交請求信息，當收到應答信息或超時時，將回調二aLLbackHandler?數。

*@paramtargetUserlD接收并處理請求消息的目標用戶二D。如果為nu工1，表示信息接收者為服務端。

*@paramin工crmacionT/pe自定義請求信息的類型

*0paraminfo請求信息

*Gparamhandler用于梵理回復信息的處理器

*@paramtag攜帶的狀態數據，將被傳遞給回調函數handler

*/

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

發送消息有幾種方式

普通發送:

調用send(StringtargetUserlD,intinformationType,byte[]info)方法進行普通發

送，即將信息寫入網絡流后就立即返回。

發送達數據塊:

調用sendBlob方法可以將大數據塊信息發送給服務端或任何其他的在線用戶。

2.處理信息

客戶端可以收到來在其它客戶端或服務端的信息、大數據塊、以及同步調用。服務端

也可以收到來自客戶端的信息（轉發的信息除外）及同步調用。那么，我們如何處理這些接

收到的信息了？無論是B艮務端，還是客戶端，都只要實現ICustomizeHandler接口即可。

/**

*自定義消息處理器

*@authordaixun

publicinterfscelCustoinizeHandler{

*處理來自其他用戶的信息（包括大數據塊信息）。

*@paramsourceUserlD發出信息的用戶工D。如果為null，表示信息來自服務端。

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

?@paraminfo信息

?/

VCidhandleinformationfiringsourceUserlD,intinformationType,fcyte[info）；

*處理來自其它在線用戶的P2E請求并返回應答信息。

*?paramsourceUserlD發送請求信息的用戶工D。如果為null，表示信息來自服務端。

*SparaminformationType自定義請求信息的類型

*?paraminfoP2E請求信息

*QreturnP2F應答信息

*/

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

）

接口說明

(1)在實現這個接口之后，只需要實例化這個具體的實現類，并在RapidPassiveEngine

的customizeHandler屬性即可自動處理接收到的消息

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

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

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

的實現中不能直接修改UI線程

(4)在客戶端，可以將ICustomizeHandler的實現類的實例傳遞給RapidPassiveEngine

的initialize方法以掛接到框架。

3.更多說明

信息發送模型

信息發送可以使用同步模型或異步模型，在方法中通過bool型post參數體現出來。

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

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

信息處理

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

理器，表示其用于處理我們應用系統的具體業務邏輯。

(1)業務處理器將在后臺線程中被調用，所以，實現業務處理器的方法中如果涉及到了

UI操作，則必須將調用轉發到UI線程。

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

某個業務處理方法非常耗時，可以考慮使用異步方式。

大數據塊

當發送大數據塊時，發送方會將其拆分為詫多連續的片段逐個發送，而在接收方會自動

將接收到的片段重組起來構成一個完整的信息。而且無論是發送大數據塊，還是普通信息,

在接收方都是調用相同的方法(ICustomizeHandler的handleinformation方法)來處理

的。

第二章好友與組

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

第三章聯系人

聯系人(IContactsOutter)是ESFramework6.0(必須與對應版本的服務端配合使用)新增的

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

/**

“用于客戶端發送與聯系人操作相關的信息和廣播。

publicinterfaceICcntactsOutter{

/**

*獲取所有在線的聯系人。

*

*/

Li3t<String>getAllOnlineScntacts();

/**

*獲取聯系人列表。

*

*/

List<String>getContacts();;

/**

*獲取組的成員。

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

*/

GrcupMatesgetGrcupMer^ers(StringgrcupID);;

/**

*獲取聯系人列表。

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

*Sparambrcadcasclype廣播信息的類型

*@parambrcadcastContent信息的內容

*Sparamaction當通道繁忙時采取的操作

*/

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

voidaeLCcnLdCCsEventLlscener(ConcdCLsflvenLListenerevencListener);

)

*聯系人監聽接口

publicinterfaceCcntact3E\'entLi3tener{

/**

*當聯系人上線時，觸發此事件。

*@paramuserID好友的工D

*/

voidccntactsCcnnected(StringuserID);

/**

*當聯系人下線時，觸發此事件。

*@paramuserID好友的UserID

?/

voidccntactsOzfline(StringuserID);

/??接收群組消息

*@parambroadcasterlD

*0paramgroup工D

*?parambroadcascType

*?parambroadcastcontent

*/

voidbrcadcastReceived(StringbroadcasterlD,StringgroupID,intbrcadcastl^e,byte[]b:

}

1.接口說明

(1)getGroupMembers會返回某個組的所有成員，并將在線成員與不在線成員區分開

來。

(2)當用戶上線或下線時，框架會回調ContactsEventListener接口的

contactsConnected或contactsOffline事件以通知其所有相關聯系人。

(3)可以通過Broadcast向任何一個組發送廣播，目標組的每個在線成員都將會通過

ContactsEventListener的BroadcastReceived事件來獲得廣播內容。

2.關注聯系人的實時狀態

在類似IM的系統中，每個運行的客戶端實例，在其運行的整個生命周期中，都需要清楚

地知道與其相關每個聯系人的實時狀態，這個需求可以這樣來實現：

(1)當某個客戶端登陸成功后,就調用getContacts方法和getAIIOnlineContacts方法

以獲取聯系人列表和所有的在線聯系人列表。這樣，就知道了所有聯系人的初始狀態。

(2)實現ContactsEventListener事件妾口，并通過setContactsEventListener方法預

定事件，然后在運行的過程中，當contactsConnected和contactsOffline事件觸發時，

就修改對應聯系人的狀態。這樣就保證我們的客戶端可以實時地知道每個相關的聯系人是否

在線。

第四章在線用戶管理、基礎功能及狀態通知

本文介紹ESFramework開發手冊(00)■■概述一文中提到的四大武器的第二個:在

線用戶管理、基礎功能及狀態通知。

在解決了發送信息和處理信息之后,還有一些基礎功能是很多分布式通信系統都需要用

到的，比如，查詢某個用戶是否在線、獲取在線用戶列表、自己掉線時得到通知，等等。

IBasicOutter下的組件，為我們解決了這些基礎問題。

1.客戶端

客戶端通過調用(comQmunicate/ramework.IBasicOutter,接口對

應的方法就可以完成基礎功能或得到相關狀態改變通知。我們可以

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

publicinterfaceIBasicOutLer{

booleanisInitializedO;

/**

*當自己被同名用戶^掉線時，觸發此事件。此時，客戶端引擎已被Dispose。

*/

voidfceingPushedOuc();

/**

?當自己被服務端踢出掉線時，觸發此事件。此時，客戶端引擎已被Dispose。

*/

voidbeingKickedCuc();

/**

?客戶端登陸場證。工RapidPassiveEzigine會在初始化時，自動調用該方法來始證用戶賬號密碼。

*@paramsystemloken系統標志。用于蛤證客戶端是否與服務端屬于同一系統。

*@parampassword登陸密碼

*@return

*/

ReapLcgcnicgcn(Stringsyater.Tcken,Stringpasswcrd);

/**

*獲取自己的工PE。

*0return通常是經過HAT之后的工PE

*/

Agile工FEgetMylPEO；

/**

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

*@return

113t<String>getAHOnlineUsers();

*查詢用戶是否在線。

*QparamuserID用戶id

*@return

*/

bccleanisUserOnline(StringuserID);

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

*^returnping耗時，單位塞秒

*/

intping();

*Ping其他在線用戶(通過服務器中轉)。

*如果目標用戶不在線，將拋出Timeout異常。

*@paramtargetUserlD要Pin#目標用戶工D

*^returnping耗時，單位至秒

*/

inrping(StringtargetUserlD);

/**

*命令服務端將目標用戶踢出。如果目標用戶不在當前路上，則直接返回。

*@paramtargetUserlD要踢出的用戶工D

*/

voidkickOur(StringrargerUserlD);

/**

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

*/

voidsendHeartBeatMessage();

狀態改變事件通知

首先，我們看看RapidPassiveEngine暴露的兩個事件：

1.beingKickedOut當自己被踢出時將觸發該事件。

2.beingPushedOut發生于當服務端將重登陸模式設置為ReplaceOld時，并且同名

用戶的成功登錄，將會把老的在線用戶擠掉而導致其下線。關于重登陸模式的更多

內容可以參見重登陸模式。

基礎API

接下來，我們簡單看看BasicOutter的幾個方法。

1.logon方法用于在登錄時驗證用戶密碼。該方法會在客戶端Rapid引擎初始化時被

引擎自動調用，所以，在使用Rapid引擎時，我們通常不需要手動調用它。如果有

的系統需要驗證除了密碼之外更多的信息，那么可以通過systemToken參數進行

傳遞這些額外信息。Logon方法返回類型為LogonResponse其屬性LogonResult

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

表示該賬號已經在其它地方登錄；如果LogonResult為1，則表示驗證賬號密碼沒

有通過，沒有通過的原因由LogonResponse的FailureCause屬性指明。

1.getAIIOnlineUsers用于獲取所有在線用戶，通常該方法僅僅用于demo,因為在

正式的系統中,在線用戶數可能是非常巨大的,這將導致GetAIIOnlineUsers的返

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

2.ping系列方法，用于獲取當前客戶端到服務端或到另一個在線客戶端的消息來回的

耗時，由于其是在應用層來模擬類似ICMP的ping,所以這個方法返回的值通常比

ICMP的ping大一些。盡管如此，在一些應用中，該Ping的結果還是有一些參考

價值的。

3.有時，我們需要命令服務器將一些惡意的用戶從服務端踢出（斷開其i車接），那么

就可以調用kickOut方法，被踢出的客戶端將會觸發上述的beingKickedOut事

件。

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

Rapid引擎，那么框架會自動發送心跳消息，所以，我們通常不需要手動調用該方

法。關于心跳消息的更多內容可以參見心跳機制。

TCP連接狀態

<municate.framework.IBasicOutter>提供了一部分基礎功能,還有

另一部分很重要的基礎功能需要涉及到客戶端的Rapid引擎，我們在這里也一并介紹一下。

客戶端如何知道史己與服務器的TCP連接的狀態及其變化了？

<municate.framework.IRapidPassiveEngine>的幾個事件來獲取這

些信息。

*當客戶端與服務器的TCF連接斷開時，將觸發此事件。

voidccnnectionlntsrrupted();

*當客戶端與服務端的TCF連接建立時會觸發此事件

voidccnnecticnRebJildStart();

?當斷線重連開始時會觸發此事件

voidrelcgin3egin();

*當斷線重連成功時，會自動登錄服務器蛉證用戶賬號密碼，并觸發此事件。如果蛉證失敗，則與服務器的連接將會斷王

*事件參數表明了登錄蛉證的結果。

voidrelcgcnCcmpleced(RespLcgcnresult);

/?*

“返回當前引擎所連接的服芬器的地址。

*0return

//

AgilelPEgetSerxTerAddre33();

//*?

*當前是否處于連接狀態。

*@return

*/

boole