ESFramework 开发手册 -- Harmony（鸿蒙）版

　　ESFramework 现在推出了纯血鸿蒙Harmony端版本，使用ArkTS开发，功能及API接口与其它端完全一致。而且，Harmony端可以与其它端（Windows、Linux、Android、iOS、Web）消息互通的。

　　此篇开发手册，我们将着重介绍ESFramework Harmony端的三大功能：基础功能（登录、状态变化通知、联系人上下线通知）、收发消息、传送文件。

一.基础功能

　　ESFramework 客户端的核心组件是 RapidPassiveEngine，在使用 ESFramework 的其它功能之前，首先需要初始化 RapidPassiveEngine。

1.初始化（登录）　

　　RapidPassiveEngine引擎里的initialize方法，其签名如下:

/**
   * @param userID 用户的ID
   * @param password 用户密码
   * @param serverIP 服务器IP地址
   * @param serverPort 服务器端口
   * @param customizeHandler 用户自定义消息处理器
   * @param (loginResult)=>{} 登录结果回调
   */
initialize(userID,password,serverIP,serverPort,customizeHandler,(loginResult)=>{})

　 customizeHandler 用于处理接收到的来自服务器或其它客户端的消息。

　　 loginResult.LogonResult 为登录返回的状态码：

enum LogonResult {
  Succeed = 0,           // 登录成功
  Failed = 1,            // 登录失败
  HadLoggedOn = 2,       // 已经在其它地方登录
  VersionMismatched = 3  // 版本不匹配
}

2. 状态变化通知

　　当客户端与服务端连接状态发生变化时，ESFramework 回调如下事件通知：

//当自己掉线时,触发事件
RapidPassiveEngine.addListener("connectionInterrupted",()=>{})

//当客户端触发重连机制时,触发事件
RapidPassiveEngine.addListener("connectionRebuildStart",()=>{})

//当客户端登录或者重连成功时,触发事件
RapidPassiveEngine.addListener("open",()=>{})

//当客户端与服务端正常断开时,触发事件
RapidPassiveEngine.addListener('close',()=>{});

　　当自己被踢下线或被挤掉线时，将通过BasicOutter的如下回调得到通知：

//其他设备登录同一账号的监听
RapidPassiveEngine.BasicOutter.addEventListener("beingPushedOut",()=>{
                    ......
                    })
//被管理员踢下线的监听
RapidPassiveEngine.BasicOutter.addEventListener("beingKickedOut",()=>{
                   ......
                  })

3.联系人上下线通知

　　当用户上/下线时，ESFramework 会通知相关联系人，会触发ContactsOutter接口的ContactsDeviceConnected或ContactsOffline事件。相关接口如下：

//联系人设备上线         
 /**
  *@param contactID 联系人ID
  * @param clientType 联系人设备类型
  */
RapidPassiveEngine.ContactsOutter.event["ContactsDeviceConnected"] = (contactID, clientType)=>{
     ...... 
} 

// 联系人下线
 /**
  * @param contactID 联系人ID
  */
RapidPassiveEngine.ContactsOutter.event["ContactsOffline"] = (contactID)=>{
     ......
};

4. 查询基础信息

　　 BasicOutter提供了用户在线状态查询、设备管理和事件处理等基础功能,相关代码如下:

//通过BasicOutter获取所有在线用户
RapidPassiveEngine.BasicOutter.getAllOnlineUsers(callback)

//通过BasicOutter获取所有我的在线设备
RapidPassiveEngine.BasicOutter.getMyOnlineDevice(callback)

//通过BasicOutter获取某个用户是否在线
RapidPassiveEngine.BasicOutter.isUserOnline(userId,callback)

//通过BasicOutter获取某个用户的网络延迟
RapidPassiveEngine.BasicOutter.ping(callback,this.userId)

//通过BasicOutter踢出某个用户
RapidPassiveEngine.BasicOutter.kickOut(this.userId)

//通过BasicOutter预定事件
RapidPassiveEngine.BasicOutter.addEventListener(eventName,callback)

二.收发消息

1. 发送消息或查询

　　客户端可以通过CustomizeOutter里的方法发送消息给其他用户,相关代码如下:

/**
   * @param informationType 自定义请求消息的类型
   * @param infobytes 请求消息
   * @param targetUserID 目标用户,为空时表示发送给服务端
   */
  send(informationType,infobytes,targetUserID)
/**
 * @param informationType 自定义请求消息的类型
 * @param infobytes 请求消息
 * @param callbackFn 如果服务器有返回应答，则回调此方法
 */
 query(informationType, infobytes, callbackFn)
/**
 * @param informationType 自定义请求消息的类型
 * @param blobContent 大的数据块信息
 * @param fragmentSize 分块传递时的分块大小
 * @param targetUserID 目标用户,为空时表示发送给服务端
 */
sendBlob(informationType,blobContent,fragmentSize,targetUserID)

2.处理接收到的消息

　　客户端需要通过实现ESFramework里的ICustomizeHandler接口，并在调用initialize方法时传入即可自动处理接收到的消息。相关接口如下：

class customizeHandler implements ICustomizeHandler{

  /**
   * 处理来自其他用户的信息(包括大数据块信息)
   * @param sourceUserID 发出信息的用户ID.如果为null,表示信息来自服务端
   * @param informationType 自定义消息类型
   * @param info 信息
   */
  handleInformation(sourceUserID, informationType, info){
        ......
}
  /**
   * 处理来自服务端或其他在线用户的请求并返回应答信息
   * @param sourceUserID 发送请求信息的用户ID.如果为null,表示信息来自服务端
   * @param informationType 自定义消息类型
   * @param info 请求信息
   * @param callBackFun 回调方法
   */
  handleQuery(sourceUserID, informationType, info, callBackFun){
    　　　......
    }
}

三.文件传送

　　　客户端可以通过FileOutter接口发送文件给其他在线用户或者服务端，流程如下:

发送方如果要发起文件传输请求,则需要调用RapidPassiveEngine.FileOutter.beginSendFile()，调用完毕后,接收方则会在文件监听事件里进入fileRequestReceived()。
接收方同意接收文件则调用RapidPassiveEngine.FileOutter.beginReceiveFile()，拒绝接收文件则调用RapidPassiveEngine.FileOutter.rejectFile()，如果拒绝，则流程结束，否则进入下一步。
发送方在文件监听事件里进入fileResponseReceived()，此时发送方便知道接收方是否接收文件。
发送方发送文件数据，接收方接收文件数据,此时发送方与接收方都进入文件监听事件里的fileTransStarted()和fileSendedProgress()。
如果文件传送过程中，接收方或发送方掉线或者取消文件传送，则文件传送被中断，流程结束,此时发送方与接收方进入文件监听事件里的fileTransDisruptted()。
如果发送方重新发送同一个文件给接收方，将会触发文件续传，文件将会从上一个断开的地方继续发送。
之后如果传输过程正常，则到最后完成文件的传送。发送方与接收方进入文件监听事件里fileTransCompleted()。

1.客户端发送文件

　　　发送方通过FileOutter里的beginSendFile发送文件请求，并且返回此次传送任务的projectID,相关代码如下

// 准备发送 --- 发送文件请求
  /**
   * @param accepterID 文件接收者
   * @param file 要传输的文件
   * @param comment 说明
   * @param step 最大传输速度
   */
 const projectID = RapidPassiveEngine.FileOutter.beginSendFile(accepterID,file,comment,step)

　　其中，file文件需要由鸿蒙的@ohos.file.picker获取,获取到文件的路径,名字,以及fd

2.客户端接收文件

　　接收方通过FileOutter里的beginReceiveFile来同意接受文件，或者通过调用rejectFile来拒绝接收文件。相关接口如下：　　

/**
   *同意接收文件 
   * @param projectID 接收文件的projectID
   * @param savePath 文件保存的路径目录
   * @param allowResume 是否打开文件续传,默认为true
   */
beginReceiveFile(projectID, savePath, allowResume)

/**
   * 拒绝文件传输
   * @param projectId 文件的projectID
   * @param cause 拒绝的原因
   */
  rejectFile(projectId,cause)

　　当用户调用beginReceiveFile方法后，发送方便会收到同意接收的回复，此时ESFramework便会自动发送文件数据包，接收方也会自动处理接收到的文件数据包。

3.取消文件的发送

　　发送方与接收方只需要通过调用FileOutter里的cancelTransfering便都可以在文件传输过程中取消文件的传输，接口定义如下：

/**
   * 取消文件传输
   * @param projectID 文件的projectID
   * @param cause 取消的原因,默认为空
   */
  cancelTransfering(projectID,cause)

4.文件相关事件通知

　　ESFramework内置了文件消息的监听事件，只需要实现IFileEventListener接口并且实例化这个具体的实现类，便可以监听文件传送的相关通知，其定义如下所示：

export class addListerFile implements IFileEventListener{

 /**
   * 监听接收到的文件消息
   * @param file 文件内容
   */
  fileRequestReceived(file){
   .......
}

/**
   * 监听接收方是否同意接收文件
   * @param file 文件内容
   * @param accept 是否同意
   */
  fileResponseReceived(file, accept){
    ......
}

/**
   * 监听文件开始发送以及接收
   * @param project 文件内容
   */
  fileTransStarted(project){
    ......
}

  /**
   *监听文件是否是续传文件
   * @param project 文件内容
   */
  fileResumedTransStarted(project){
      ......
}

/**
   * 监听文件的发送/接收进度
   * @param projectId 文件的projectID
   * @param totlaSize 文件的总大小
   * @param transfered 文件的发送/接收进度
   * @param userID 发送方ID
   */
  fileSendedProgress(projectId,totlaSize,transfered,userID) {
      ......
  }

/**
   * 监听文件断开
   * @param projectId 断开文件的projectID
   * @param disrupttedType 断开的自定义消息
   * @param cause 断开的原因
   */
  fileTransDisruptted(projectId, disrupttedType, cause){
   ......
}

/**
   * 监听文件发送/接收成功
   * @param projectId 文件的projectID
   */
  fileTransCompleted(projectId){
      ......
}
}

5.文件续传

　　如果文件传输因为某些原因中断（比如取消传送、或者是因为网络断开而中断），ESFramework 都会保存中断文件的进度。如果发送方重新发送同一个文件，ESFramework会续传该文件，而不是从头开始传送。

四. 使用ESFramework.har包

　　将ESFramework的har包引入到项目根目录下的entry/libs里，如果没有libs文件夹，可以自行创建一个。

　　然后，修改entry/oh-package.json5里的dependencies，如图所示：　　　　　　

　之后点击Sync Now ，等待同步完成后，便可以在项目中使用ESFramework。

五. 入门Demo

ESFramework的入门Demo的鸿蒙版实现： ESFramework Demo －－入门Demo鸿蒙版（Harmony）

Demo的鸿蒙端可与现有的 Windows、Linux、Android、iOS、Web 端互通！