ESFramework 开发手册(04) -- 动态组

  最新的 ESFramework v7.0 新增了动态组功能,位于  ESPlus.Application.DynamicGroup 命名空间,动态组包含两种:持久组和临时组。

(1)持久组:不仅在运行进程的内存中存在,而且还存在于持久化介质中,如数据库中。

(2)临时组:仅仅在运行进程的内存中存在,不需要持久化存储。

正如其名,临时组是一个临时的东西,当第一个用户加入时创建它,当最后一个用户从组中退出时,就销毁它了。

比如:微信群就是一个持久组,而在微信群中发起一个群视频聊天,就是临时组。 

一.  动态组约定 

       ESFramework 动态组有如下约定:

(1)当第一个人加入组时,服务端将在内存中创建组,当最后一个人从组中退出时,则在内存中销毁该组。

(2)可以通过动态组的属性来控制:当目标用户掉线时,是否要从组中移除。

(3)ESFramework 动态组不直接与数据库关联,而是:动态组服务端提供API允许向 ESFramework 注入从数据库中加载的持久组;以及提供事件通知上层应用去更新DB中的持久组。

二. 动态组功能服务端详解

  在服务端定义了ESPlus.Application.DynamicGroup.IDynamicGroupController接口,当服务端引擎初始化成功后,可以通过其暴露的DynamicGroupController属性来使用动态组功能。

    /// <summary>
    /// 动态组控制器。
    /// 1.动态组分为两种类型:组员掉线就从组中移除,或者不移除(默认值)。服务端通过IDynamicGroupController.SetGroupActionType方法可以设定这个类型。
    /// 2.巧妙使用PresetGroup方法,可以在服务端启动的时候,就预设一些已经存在的组(比如从DB中加载的群)。
    /// </summary>
    public interface IDynamicGroupController
    {
        /// <summary>
        /// 当服务端接收到要在组内转发的广播消息时,触发此事件。参数:broadcasterID - groupID - broadcastType - broadcastContent - tag
        /// </summary>
        event CbGeneric<string, string, int, byte[], string> BroadcastReceived;

        /// <summary>
        /// 第一个成员加入组将导致动态组被创建,触发该事件。参数:groupID
        /// </summary>
        event CbGeneric<string> GroupCreated;

        /// <summary>
        /// 最后一个成员退出组将导致动态组被销毁,触发该事件。参数:groupID
        /// </summary>
        event CbGeneric<string> GroupDestroyed;

        /// <summary>
        /// 当新成员加入组时,触发该事件。参数:groupID - memberID
        /// </summary>
        event CbGeneric<string, string> SomeoneJoinGroup;

        /// <summary>
        /// 当成员退出组时,触发该事件。参数:groupID - memberID
        /// </summary>
        event CbGeneric<string, string> SomeoneQuitGroup;

        /// <summary>
        /// 当某些人被拉入组时,触发该事件。参数:groupID - memberIDs - operatorID。
        /// 当OperatorID为null时,表示操作者是服务端。
        /// </summary>
        event CbGeneric<string, List<string>, string> SomeoneBePulledIntoGroup;

        /// <summary>
        /// 当某些人被移除组时,触发该事件。参数:groupID - memberIDs - operatorID
        /// 当OperatorID为null时,表示操作者是服务端。
        /// </summary>
        event CbGeneric<string, List<string>, string> SomeoneBeRemovedFromGroup;

        /// <summary>
        /// 当目标组的Tag发生变化时,触发该事件。groupID - newTag - operatorID
        /// </summary>
        event CbGeneric<string, string, string> GroupTagChanged;

        /// <summary>
        /// 在组内广播信息。
        /// </summary>        
        /// <param name="groupID">接收广播信息的组ID</param>
        /// <param name="broadcastType">广播信息的类型</param>
        /// <param name="broadcastContent">广播的内容</param>      
        /// <param name="tag">附加信息</param>          
        void Broadcast(string groupID, int broadcastType, byte[] broadcastContent, string tag);

        /// <summary>
        /// 将用户拉入组。
        /// </summary>       
        void PullIntoGroup(string groupID, List<string> members);

        /// <summary>
        /// 将用户从动态组中移除。
        /// </summary>   
        void RemoveFromGroup(string groupID, List<string> members);   

        /// <summary>
        /// 获取组成员列表。
        /// </summary>        
        List<string> GetGroupMembers(string groupID);

        /// <summary>
        /// 获取所有组友列表。
        /// </summary>      
        List<string> GetGroupmates(string userID);

        /// <summary>
        /// 获取所有动态组的ID列表。
        /// </summary>       
        List<string> GetGroupList();

        /// <summary>
        /// 设置组反应类型(当组成员掉线时)。
        /// 注意:最好是在GroupCreated事件中,即组被创建时就立即设置该组的ActionType。
        /// 如果不设置,则默认为:当目标组中的成员掉线时,不会从该组中移除成员。
        /// </summary>
        /// <param name="groupID">目标组ID</param>
        /// <param name="quitGroupWhenOffline">当目标组中的成员掉线时,是否从该组中移除?默认值:false。</param>
        void SetGroupActionType(string groupID, bool quitGroupWhenOffline);

        /// <summary>
        /// 预设组。
        /// 如果目标组ID已经存在,将抛出异常。        
        /// </summary>
        /// <param name="groupID">组ID</param>
        /// <param name="members">组成员列表</param>
        void PresetGroup(string groupID, List<string> members);

        /// <summary>
        /// 设置目标组的Tag。组成员将收到GroupTagChanged事件通知。
        /// 前提:目标组必须存在,否则将忽略该调用。
        /// </summary>
        /// <param name="groupID">目标组ID</param>
        /// <param name="tag">新的tag</param>
        void SetGroupTag(string groupID, string tag);
/// <summary> /// 获取目标组的Tag。 /// </summary> /// <param name="groupID">目标组ID</param> string GetGroupTag(string groupID);     }

(1)BroadcastReceived 当服务端接收到要在组内转发的广播消息时,触发此事件,如组内成员调用在客户端调用 IDynamicGroupOutter 的 Broadcast 方法广播消息时,就会触发。

(2)SetGroupActionType  第二个参数quitGroupWhenOffline 当目标组中的成员掉线时,是否从该组中移除,该参数可将组分为不同的类型。

         true:一般用于临时群,组成员掉线后,直接将该成员从组中移除; false:一般用于持久群。

(3)PresetGroup 可以在服务端启动时,预先将一些已经存在的群组装载进去(如装载DB中的群)。 

三. 动态组功能客户端详解

  在客户端,定义了ESPlus.Application.DynamicGroup.Passive.IDynamicGroupOutter 接口,我们可以通过IRapidPassiveEngine暴露出的DynamicGroupOutter属性,来使用动态组功能。 

     public interface IDynamicGroupOutter
    {
        /// <summary>
        /// 当接收到某个组内的广播消息时,触发此事件。参数:broadcasterID - groupID - broadcastType - broadcastContent - tag。
        /// 如果broadcasterID为null,表示是服务端发送的广播。
        /// </summary>
        event CbGeneric<string, string, int, byte[], string> BroadcastReceived;

        /// <summary>
        /// 当某个动态组的组友掉线时,触发此事件。        
        /// </summary>
        event CbGeneric<string> GroupmateOffline;

        /// <summary>
        /// 当某个动态组的组友上线时,触发此事件。        
        /// </summary>
        event CbGeneric<string> GroupmateOnline;

        /// <summary>
        /// 当新成员加入组时,触发该事件。参数:groupID - memberID
        /// </summary>
        event CbGeneric<string, string> SomeoneJoinGroup;

        /// <summary>
        /// 当成员退出组时,触发该事件。参数:groupID - memberID
        /// </summary>
        event CbGeneric<string, string> SomeoneQuitGroup;

        /// <summary>
        /// 当某人被拉入组时,触发该事件。参数:groupID - memberIDList - operatorID。
        /// 当OperatorID为null时,表示操作者是服务端。
        /// </summary>
        event CbGeneric<string, List<string> ,string> SomeoneBePulledIntoGroup;

        /// <summary>
        /// 当某人被移除组时,触发该事件。参数:groupID - memberIDList - operatorID
        /// 当OperatorID为null时,表示操作者是服务端。
        /// </summary>
        event CbGeneric<string, List<string>, string> SomeoneBeRemovedFromGroup;

        /// <summary>
        /// 当自己被拉入组时,触发该事件。参数:groupInformation - operatorID。
        /// 当OperatorID为null时,表示操作者是服务端。
        /// </summary>
        event CbGeneric<GroupInformation, string> BePulledIntoGroup;

        /// <summary>
        /// 当自己被移除组时,触发该事件。参数:groupID - operatorID
        /// 当OperatorID为null时,表示操作者是服务端。
        /// </summary>
        event CbGeneric<string, string> BeRemovedFromGroup;


        /// <summary>
        /// 当收到加入组的邀请时,触发该事件。参数:GroupInformation - OperatorID。        
        /// 注意:收到邀请时,自己尚未加入组。若接受邀请,则可以调用JoinGroup加入目标组。
        /// </summary>
        event CbGeneric<GroupInformation, string> BeInvitedJoinGroup;

        /// <summary>
        /// 当目标组的Tag发生变化时,触发该事件。GroupID - newTag - OperatorID
        /// </summary>
        event CbGeneric<string, string, string> GroupTagChanged;

        /// <summary>
        /// 在目标组内广播消息。
        /// </summary>
        /// <param name="groupID">目标组ID</param>
        /// <param name="broadcastType">广播消息类型</param>
        /// <param name="broadcastContent">广播消息内容</param>
        /// <param name="tag">Tag</param>
        void Broadcast(string groupID, int broadcastType, byte[] broadcastContent, string tag);

        /// <summary>
        /// 获取我的所有组。
        /// </summary>
        /// <returns>组ID列表</returns>
        List<string> GetMyGroups();

        /// <summary>
        /// 获取组信息。
        /// </summary>
        /// <param name="groupID">目标组ID</param>
        /// <param name="useLocalCache">是否使用本地缓存?如果为true且本地有缓存,则直接从本地缓存获取组信息。</param>
        /// <returns></returns>        
        GroupInformation GetGroupInformation(string groupID, bool useLocalCache);

        /// <summary>
        /// 获取所有在线组友的列表。
        /// </summary>        
        List<string> GetOnlineGroupmates();

        /// <summary>
        /// 设置目标组的Tag。其它组成员将收到GroupTagChanged事件通知。
        /// 前提:目标组必须存在,否则将忽略该调用。
        /// </summary>
        /// <param name="groupID">目标组ID</param>
        /// <param name="tag">新的tag</param>
        void SetGroupTag(string groupID, string tag);

        /// <summary>
        /// 加入组。
        /// </summary>  
        void JoinGroup(string groupID);

        /// <summary>
        /// 退出组。
        /// </summary>  
        void QuitGroup(string groupID);

        /// <summary>
        /// 将用户拉入组。
        /// </summary>       
        void PullIntoGroup(string groupID, List<string> members);

        /// <summary>
        /// 将用户从动态组中移除。
        /// </summary>   
        void RemoveFromGroup(string groupID, List<string> members);

        /// <summary>
        /// 邀请用户加入动态组。被邀请的用户将会触发BeInvitedJoinGroup事件。
        /// </summary>        
        void InviteJoinGroup(string groupID, List<string> users);

        /// <summary>
        /// 清空本地缓存的所有组信息。(在掉线重连成功后,本地缓存有可能已经过时)
        /// </summary>
        void ClearLocalCache();
    }   

(1)GetMyGroups 获取我所在的所有的组。

(2)GetOnlineGroupmates 获取所有在线组友的列表 (所有组中的在线组友集合)。

(3)GetGroupInformation 方法可以查询指定组的 详细信息(包括该组的ID、所有成员ID、组Tag)。

(4)JoinGroup 加入群组 ,当传入的groupID在服务端不存在时,会自动生成该组,并将该调用者加入到该群组中。 同时服务端也会触发 GroupCreated 事件。

(5)PullIntoGroup 将某些用户拉入到指定的组中去,被拉入的用户将会触发 BePulledIntoGroup 事件,同时该组中其他的组友将会触发 SomeoneBePulledIntoGroup 事件。

(6)Broadcast 向指定组发送广播消息, 其他组内成员将会触发 BroadcastReceived 事件(同时服务端也会触发 BroadcastReceived 事件)来接收该广播消息。 

四.补充说明

1.如何实现在客户端创建群?

在客户端调用IDynamicGroupOutter 的 JoinGroup方法或 PullIntoGroup 方法,都可以动态创建一个群。

如果需要将该群持久化存储到DB中,可以在服务端预定IDynamicGroupController 的 GroupCreated 事件来得到通知。

2.如何实现客户端加群申请?

这个可以通过ESFramework的自定义消息来实现:

申请者A向管理者B发送一条自定义消息表示申请加入某群,当A收到B的同意加入的回复后,就调用IDynamicGroupOutter 的 JoinGroup方法正式加入群中。

3.如何在服务端方便地保存动态组的相关信息(如管理员ID、群公告、群说明等等)?

可以巧妙使用Group的Tag来保存与动态组相关的信息,服务端和客户端都可以通过SetGroupTag来修改动态组携带的Tag信息。 

                

-----------------------------------------------------------------------------------------------------------------------------------------------   

下载免费版本的ESFramework 以及 demo源码  

阅读 更多ESFramework开发手册系列文章

Q Q:168757008

官网:www.oraycn.com

导航

首页

官方网站

联系我们

立即咨询 

站内搜索

ESFramework 通信框架

详细说明

SDK与Demo下载

ESFramework FAQ

版本变更记录

OMCS 语音视频框架

详细说明

SDK与Demo下载

OMCS FAQ

版本变更记录

OrayTalk 企业即时通讯系统

详细说明

客户端下载

OVCS 视频会议系统

详细说明

源码下载

傲瑞实用组件

SDK下载

NPusher 推流组件

NPuller   拉流组件

MCapture 语音视频采集组件

MFile 语音视频录制组件

MPlayer 语音视频播放组件

OAUS 自动升级系统

StriveEngine 轻量级的通信引擎

傲瑞组件 FAQ

授权

授权流程

产品选购指南

授权方案说明

授权SDK使用说明

其它

支持信创国产化

SDK使用技巧

联系我们