ESFramework開發(fā)手冊--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來發(fā)送信息，以及實現(xiàn)

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

信息就可以了。

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

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

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

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

接口定義如下：

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

?QparaminformationType自定義信息類型

*@paraminfo信息

*/

voidsenddntinformationType,byte[]info）；

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

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

*?paraminformationType自定義信息類型

*@paraminfo信息

*/

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

/**

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

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

*@paraminfo請求信息

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

*/

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

/**

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

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

*QparaminformationType自定義信息類型

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

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

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

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

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

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

*GparaminformationType自定義信息類型

*@paraminfo信息

?/

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

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

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

*?paraminformationType自定義信息類型

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

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

*/

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

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

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

*@paraminformationType自定義請求信息的類型

*@paraminfo請求信息

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

*/

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

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

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

*@paraminformationType自定義請求信息的類型

*@paraminfc請求信息

*@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)方法進行普通發(fā)

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

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

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

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

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

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

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

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

見ACK機制。

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

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

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

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

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

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

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

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

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

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

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

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

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

2.處理信息

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

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

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

*自定義消息處理器

*@authordaixun

publicinterfacelCustcmizeMandler{

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

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

*@paraminformationType自定義信息類型

*@paraminfo信息

*/

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

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

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

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

*QparaminfoP2耳青求信息

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

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

)

接口說明

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

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

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

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

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

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

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

的initialize方法以掛接到框架。

3.更多說明

信息發(fā)送模型

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

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

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

信息處理

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

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

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

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

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

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

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

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

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

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

的。

第二章好友與組

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

第三章聯(lián)系人

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

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

*用干客戶湍發(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廣播信息的類型

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

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

*/

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

voidsetCcntactsEventListener(ContactsEventListenereventListener);

}

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

publicinterfaceContactsEv^entListener{

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

@paramuserID好友的工D

voidcontactsCcnnected(StringuserID);

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

*@paramuserID好友的U§er1D

voidcontacrsOffline(StringuserID);

/**接收群組消息

*@parambroadca3X；erID

*@paramgroupID

*[parambroadcastType

*?parambroadcastcontent

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

)

1.接口說明

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

來。

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

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

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

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

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

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

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

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

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

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

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

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

院

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

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

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

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

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

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

1.客戶端

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

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

<RapidPassiveEngine>K)getBasicOutter。方法來獲取IBasicOutter引甩

publicinterfaceIBasicOutcer{

booleanislnitializedf);

/**

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

*/

voidbeingPushedOut();

/**

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

*/

voidbeingKickedOut();

/**

*客戶端登陸始證。工RapidPassiveEngine會在初始化時，自動調(diào)用該方法來蛉證用戶賬號密碼。

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

*@parampassword登陸擊碼

*@return

ReapLogonlogon(StringsystemTcken,Stringpassword);

/★*

*獲取自己的工PE。

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

*/

AgilelPEgetMylPEO；

/**

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

*@return

List<String>getAHOnlineUsers();

*查詢用戶是否在線。

*@paramuserID用戶id

*@return

*/

booleaniaUserOnline(StringuserID);

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

*Qreturnping耗時，單位塞秒

*/

intping();

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

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

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

*@returnping耗時，單位塞秒

*/

intping(StringtargetUserlD);

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

*@paramtargetUserir要踢出的用戶工D

*/

voidkickOut(StringtargerUserlD);

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

*/

voidsendHeartBeatMessage();

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

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

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

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

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

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

基礎(chǔ)API

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

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

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

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

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

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

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

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

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

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

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

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

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

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

價值的。

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

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

件。

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

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

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

TCP連接狀態(tài)

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

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

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

municataframework.IRapidPassiveEngine）的幾個事件來獲取這

些信息。

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

voidconnectionlnterruptedO;

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

voidconnectionRebuildStart();

?當斷線重連開始時會觸發(fā)此事件

*/

voidrelogin3egin();

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

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

voidrelogonCompleted(RespLogonresult);

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

*?return

Agile工PEgetServerAddress(