傲瑞组件开发手册(06) -- 消息推送组件 NPush

       NPush是跨客户端平台的消息推送框架。用于实现类似微信的朋友圈功能,支持推送朋友圈消息,拉取朋友圈消息,查看目标好友的动态,点赞,评论等功能。

  NPush服务端基于.NET,DB支持SqlServer和MySQL,客户端平台支持PC(.NET)、Android、iOS、HTTP。

一.基本概念

       在NPush中,一条朋友圈动态消息被称为一个Moment(精彩瞬间)。发送一条Moment,称之为Push;获取朋友圈动态称之为Pull。对Moment的评论称之为Remark(点赞是Remark的一种特殊形式,可在应用层自定义)。

       当Pull的时候,可以分为下拉和上拉。下拉,即请求最新的动态。上拉,则是请求较老的动态。就像在微信朋友圈UI中向上滑动和向下滑动的含义一样。在NPush中,使用bool参数latest(是否最新)来区分当前的Pull请求是下拉(latest为true)还是上拉(latest为false)。 

        NPush框架提供了服务端引擎 IServerEngine和客户端引擎 IMomentsClient,了解了这两个核心组件,就可以使用NPush来开发朋友圈功能了。 

二.NPush 服务端引擎

  NPush服务端引擎接口IServerEngine相当简洁,方便使用,其定义如下所示:

    /// <summary>
    /// NPush服务端引擎接口。
    /// </summary>
    public interface IServerEngine
    {
        /// <summary>
        /// 日志文件的路径。默认为运行目录下的AppLog.txt文件。
        /// </summary>
        string LogFilePath { get; set; }

        /// <summary>
        /// NPush服务器配置选项。必须在Initialize方法调用之前设置才有效。
        /// </summary>
        NPushConfiguration Configuration { get; set; }

        /// <summary>
        /// 当前用户数。
        /// </summary>
        int UserCount { get; }

        /// <summary>
        /// 初始化。
        /// </summary>        
        /// <param name="port">为客户端提供服务的端口</param>    
        /// <param name="verifier">用户帐号密码验证器。如果不需要验证,可以传入null。</param>
        /// <param name="friendProvider">好友关系提供者</param>    
        /// <param name="persister">数据持久化接口</param>    
        void Initialize(int port, IUserVerifier verifier, IFriendProvider friendProvider, IMomentsPersister persister);

        /// <summary>
        /// 获取在线用户列表。
        /// </summary>        
        List<string> GetUsers();     
    }

      最简单地,只要调用引擎的Initialize方法,即可启动服务端。 Initialize方法需要注入三个关键的组件:

(1)IUserVerifier 用于验证登录的用户是否合法。

(2)IFriendProvider 用于提供好友关系。即当我推送一个Moment时,服务端通过该接口知道我有哪些好友,然后将该Moment推送给他们。

(3)IMomentsPersister 用于服务端与DB之间的交互,完成Moment的持久化存储。NPush内置了DBMomentsPersister类,支持SqlServer和MySQL。

         如果需要支持其它的数据库类型,如Oracle等,则只需要自己实现 IMomentsPersister 接口即可。

      另外,IServerEngine 的 Configuration 属性也很重要,在使用时,需要根据具体应用设置合适的值。

    /// <summary>
    /// NPush服务器配置选项。
    /// </summary>
    [Serializable]
    public class NPushConfiguration
    {
         /// <summary>
        /// 针对每个用户的Push队列和Pull队列的大小。默认值:200。
        /// </summary>
        public int MaxQueueSize {get; set;}      
        /// <summary>
        /// 对于Pull请求,每次回复的列表中包含Moments的最大个数。默认值:20。
        /// </summary>
        public int MaxCountOfMoments4Request {get; set;}    
         /// <summary>
        /// 当服务端重启时,为目标用户重建Push队列或Pull队列时,需要重DB中加载最新的消息的数量。默认值:20。
        /// </summary>
        public int LoadLatestCountOnStart  {get; set;}
    }

      注释已经描述得很清楚了,不再赘言。 

三.NPush 客户端引擎

   NPush客户端引擎接口是IMomentsClient,二次开发时,我们只需要使用这一个接口即可。

1.基础API

        /// <summary>
        /// 当与节点服务器之间的TCP连接断开时,触发此事件。(连接断开将会自动重连)
        /// </summary>
        event CbGeneric ConnectionInterrupted;

        /// <summary>
        /// 当同名的帐号登录当前连接的服务器时,自己将被挤掉线(不再自动重连),触发此事件。
        /// </summary>
        event CbGeneric PushedOut;

        /// <summary>
        /// 当与服务器重连上并登录完成后,触发此事件。请注意查看事件参数LoginResultType,如果登录失败,则表示当前客户端实例已经失效。
        /// </summary>
        event CbGeneric<LoginResultType> RelogonCompleted;        

        /// <summary>
        /// 与节点服务器之间的TCP连接是否正常?
        /// </summary>
        bool Connected { get; }

        /// <summary>
        /// 当前对象是否已经被释放?
        /// </summary>
        bool IsDisposed { get; }

        /// <summary>
        /// 初始化,并登录到服务器。
        /// </summary>
        /// <param name="serverIP">服务器的IP</param>
        /// <param name="port">服务器的端口</param>
        /// <param name="userID">登录帐号</param>
        /// <param name="pwd">登录密码</param>              
        /// <returns>登录结果</returns>
        LoginResultType Initialize(string serverIP, int port, string userID, string pwd);

(1)调用 IMomentsClient 的Initialize方法,将会与NPush服务端建立TCP连接,并用帐号密码登录。

(2)如果在客户端运行的过程中,与服务器之间的TCP连接中断,则将触发 ConnectionInterrupted 事件,并开始自动重连。

          当重连成功并重新登录,则触发 RelogonCompleted 事件。

(3)Connetcted 属性反应了当前与服务器的连接是否正常。

(4)如果在客户端运行的过程中,有同名用户在其它地方重复登录,当前 IMomentsClient 将被挤掉线,并触发 PushedOut 事件。

2. 发送/推送 Moment

        /// <summary>
        /// 在朋友圈发送消息。
        /// </summary>
        /// <param name="msgType">消息类型。</param>
        /// <param name="content">消息内容</param>
        /// <param name="tag">附加tag</param>
        /// <returns>返回PassiveID</returns>
        string Push(int msgType, byte[] content, string tag);

通过这三个参数,我们可以自定义不同类型、各种格式的 Moment。

请注意 Push 方法的返回值,这个返回值称为PassiveID,是由客户端引擎为当前发送的Moment生成的一个ID,在服务端全局而言,它并不一定是唯一的。PassiveID最主要的作用,是用于删除自己刚发送的 Moment 或 Remark。后面的删除Moment/Remark 的API支持使用PassiveID作为参数,这样,对于二次开发是很方便的。

3.拉取Moment

         /// <summary>
        /// 当调用Pull方法请求moment列表,得到服务器的回复时,触发此事件。
        /// </summary>
        event CbGeneric<UserMoments> ResponseMomentReceived;

        /// <summary>
        /// 拉取我的朋友们发的消息。当收到服务器回复,将触发ResponseMomentsReceived事件。
        /// </summary>
        /// <param name="startPullIndex">从哪个index的消息开始拉取(不包含该index对应的那条)。如果startPullIndex小于0,表示拉取最新的N条。</param>
        /// <param name="latest">latest为true,表示拉取更新的(大于startPullIndex);为false表示拉取之前的(小于startPullIndex)。</param>        
        void Pull(long startPullIndex, bool latest);

        /// <summary>
        /// 拉取目标用户所发的消息。当收到服务器回复,将触发ResponseMomentsReceived事件。
        /// </summary>
        /// <param name="ownerID">所要拉取的目标用户的ID</param>
        /// <param name="startPushIndex">从哪个index的消息开始拉取(不包含该index对应的那条)。如果startPushIndex小于0,表示拉取最新的N条。</param>     
        /// <param name="latest">latest为true,表示拉取更新的(大于startPullIndex);为false表示拉取之前的(小于startPullIndex)。</param>        
        void Pull(string ownerID, long startPushIndex, bool latest);

(1)Pull方法有个重载。带两个参数的Pull方法,用户获取自己所有好友的动态。带三个参数的Pull方法用于获取指定好友发送的动态 -- 相当于查看他的主页。

(2)第一个Pull方法使用了 PullIndex 作为参数 ;第二个Pull方法,使用 PushIndex 作为参数。这里要重点解释一下 PullIndex 和 PushIndex的区别。

         可以想象这样的模型: 服务端为每个用户都建立了两个队列,一个是Push队列,一个是Pull队列。每个Push队列和Pull队列都有一个自己的Index计数。

          当一个用户发送一个Moment时,会在他的Push队列中加入一个Moment,并生成一个PushIndex值(连续增长)来标记它。

         同时,会在该用户的每个好友的Pull队列里,加入一个指针指向源Moment,并生成一个PullIndex 值(连续增长)来标记这个指针。

         至此,当调用第一个Pull方法时,服务端会从该用户的Pull队列中获取数据;当调用第二个方法时,则从目标用户的Push队列中获取数据。

(3)Pull请求被服务器处理后,返回的结果将触发 ResponseMomentReceived 事件。

4.评论、删除、通知

         /// <summary>
        /// 当朋友圈有新的动态时,触发该事件。参数:ownerID - infoType - pullIndex
        /// </summary>
        event CbGeneric<string, int ,long> NewMomentNotified;   

        /// <summary>
        /// 当朋友圈有我相关的新评论时,触发该事件。参数:remarkUserID - ownerID - pushIndex - remarkType - content - tosb
        /// </summary>
        event CbGeneric<string ,string, long , int ,string ,string> NewRemarkNotified;

        /// <summary>
        /// 当朋友圈消息被删除时,触发此事件。参数:ownerID - pushIndex
        /// </summary>
        event CbGeneric<string, long> RemoveMomentNotified;

        /// <summary>
        /// 当评论被删除时,触发此事件。参数:ownerID - pushIndex - remarkPassiveID
        /// </summary>
        event CbGeneric<string, long, string> RemoveRemarkNotified;
       
        /// <summary>
        /// 为朋友圈某条消息评论、点赞、回复评论。
        /// </summary>
        /// <param name="ownerID">目标消息的发送者ID</param>
        /// <param name="momentPushIndex">目标消息的PushIndex</param>
        /// <param name="remarkType">评论的类型。自定义。比如0表示赞,1表示评论,2表示回复。</param>
        /// <param name="content">评论或回复的内容</param>
        /// <param name="tosb">如果是评论回复,则@用户的帐号</param>
        /// <returns>返回PassiveID</returns>
        string Remark(string ownerID ,long momentPushIndex ,int remarkType ,string content ,string tosb);

        /// <summary>
        /// 删除自己发的某条消息。
        /// </summary>
        /// <param name="momentPushIndex">目标消息的PushIndex</param>
        void RemoveMoment(long momentPushIndex);
       
        /// <summary>
        /// 删除自己发的某条消息。
        /// </summary>
        /// <param name="momentPassiveID">目标消息的PassiveID</param>
        void RemoveMoment(string momentPassiveID);

        /// <summary>
        /// 删除自己发的某条评论。
        /// </summary>
        /// <param name="ownerID">目标消息的发送者ID</param>
        /// <param name="momentPushIndex">目标消息的PushIndex</param>
        /// <param name="remarkPassiveID">目标评论的PassiveID</param>
        void RemoveRemark(string ownerID, long momentPushIndex, string remarkPassiveID);
     

(1)Remark 方法的 remarkType 参数,使得我们可以定义多种类型的评论。比如,使用一个特殊的 remarkType 值,用来表示常见的 “点赞”功能。

(2)当删除一个 Moment 或 Remark 时,在服务器上并不是真的将其删除,而是将其 IsValid 属性设置为false。所以,客户端在加载显示时,要判断 IsValid 的值。

四.NPush入门Demo

 

 

 

下载 更多傲瑞组件以及Demo源码 

阅读 更多傲瑞组件开发手册系列文章 

Q Q:168757008 

官网:http://www.oraycn.com/ 

导航

首页

官方网站

立即咨询 

站内搜索

ESFramework 通信框架

详细说明

SDK下载

ESFramework FAQ

版本变更记录

OMCS 语音视频框架

详细说明

SDK下载

OMCS FAQ

版本变更记录

OrayTalk 企业即时通讯系统

详细说明

客户端下载

傲瑞实用组件

SDK下载

NPush 消息推送组件

StriveEngine 轻量级的通信引擎

MFile 语音视频录制组件

MCapture 语音视频采集组件

MPlayer 语音视频播放组件

OAUS 自动升级系统

傲瑞组件 FAQ

授权

授权流程

产品授权说明

产品选购指南

授权SDK使用说明

其它

SDK使用技巧

联系我们

电话:027-87638960

Q Q:168757008

邮件:master@oraycn.com