@nealcaffrey 2015-03-23T08:22:46.000000Z 字数 6051 阅读 514

Windows Phone 实时通信服务(v2)

简介

在阅读本开发指南之前，请先阅读下《实时通信开发指南(v2)》，了解实时通信的基本概念和模型。

目前我们的实时通信服务仅支持 Windows Phone Silverlight 运行时，支持微软新一代的全平台统一运行时的 LeanCloud SDK for Windows Runtime 会尽快发布，本文档所提及的概念以及示例代码都兼容以上提及的 2 个运行时。

安装

为了支持实时聊天，LeanCloud SDK for Windows Phone Silverlight 依赖于一个开源的第三方的 WebSocket 的库，所以推荐开发者从 Nuget 上下载我们的 SDK。

初始化

导入 SDK 之后，在 App.xaml 的构造函数中添加如下代码：

public App()
{
   //generated code by visual studio
   ...
   AVClient.Initialize("你的 AppId", "你的 AppKey");
   ...
}

单聊

发送消息

此场景类似于微信的私聊，微博的私信以及 QQ 单聊的场景，我们在 V2 版本内建立了一个统一的概念来描述聊天的各种场景：对话 — AVIMConversation，在《实时通信开发指南(v2)》里面有详细的介绍。

一天汉献帝赏赐了刘皇叔一个新手机，刘备想发一条消息向曹操炫耀一下，下面的代码将帮助他实现这一功能：

public async void Sanguo_Episode1()
{
    AVIMClient client = new AVIMClient("Liubei");//刘备用自己的名字作为 ClientId。
    //注：ClientId 在单个应用中保持唯一即可，值为任意长度不超50的字符，由开发者自己维护
    await client.ConnectAsync();//刘备登陆到 LeanCloud 服务端
    AVIMConversation conversationWithCaocao = await client.StartConversationAsync("Caocao");
    //创建一个只包含 刘备 和 曹操 对话，这就是单聊。
    await conversationWithCaocao.SendTextMessageAsync("丞相，皇上又赏赐我新手机了！");
    //调用 AVIMConversation.SendTextMessageAsync 方法发送消息。
}

接受消息

紧接着上面的情景，曹操正在丞相府宴请文武百官，拿出手机，打开应用，登陆一下，以下代码会可以让曹操收到刘备的消息：

public async void Sanguo_Episode1_1()
{
    AVIMClient client = new AVIMClient("CaoCao");//刘备用自己的名字作为 ClientId。
    await client.ConnectAsync();
    client.OnMessageReceieved += (s, e) =>
    {
        if (e.Message is AVIMTextMessage)
        {
            string words = ((AVIMTextMessage)e.Message).TextContent;
            //words 的内容就是：丞相，皇上又送我新手机了！
        }
    };
}

运行以上代码之后，在 LeanCloud 网站的控制台找到指定的应用，打开存储管理控制台，可以看到默认表 _Conversation中多了一条数据，该条数据的字段解释如下：

name：String，对话唯一的名字。
m：Array，对话中成员的列表。
lm：Date，对话中最后一条消息发送的时间。
c：String，对话的创建者的 ClientId
mu：Array，对话中设置了静音的成员，仅针对 iOS 以及 Windows Phone 用户有效
attr：Object，开发者设置的对话的自定义属性。

群聊

此场景类似于微信的多人聊天群组，以及 QQ 群，请注意这里的群聊指的是持久化存储的一个群组的概念，比如 QQ 群，除非群主解散该群，这个群应该是一直存在于我的QQ群列表中。关于临时群组聊天（聊天室）会在之后做单独解释。

发送消息

又有一天，刘备赴宴丞相府，一番青梅煮酒之后，刘备回到家中，发现京城已经不可久留，便想群发一条消息给关羽，张飞以及自己的两位夫人，告诉他们要做好撤离京城的准备，他需要做的事情是：

第一步：建立一个家庭成员列表
第二步：新建一个对话，把家庭成员列表里面的成员列为对话的参与人员
第三步：发送一条消息

以下代码将实现这个需求：

public async void Sanguo_Eposode2()
{
    AVIMClient client = new AVIMClient("LiuBei");//刘备用自己的名字作为 ClientId。
    await client.ConnectAsync();//刘备登陆到 LeanCloud 服务端
    #region 第一步：建立一个家庭成员列表
    IList<string> familyMembers = new List<string>();
    familyMembers.Add("GuanYu");
    familyMembers.Add("ZhangFei");
    familyMembers.Add("Wife01");
    familyMembers.Add("Wife02");
    //把家里人都作为群成员
    #endregion
    #region 第二步：新建一个对话，把家庭成员列表列为对话的参与人员
    AVIMConversation familyConversation = await client.StartConversationAsync(familyMembers);
    //创建一个对话，对话包含了 刘关张以及两位夫人
    #endregion
    #region 第三步：发送一条消息
    await familyConversation.SendTextMessageAsync("曹操已对我起了疑心，我们还是赶紧跑路吧……");
    #endregion
}

接受消息

群聊的接受消息于单聊的接受消息是一样的。

关二爷打开应用登陆一下就会收到刘备大哥发来的消息，然后关羽给予了大哥回应：

AVIMConversation NitifiedConversation = null;
public async void Sanguo_Episode2_1()
{
    AVIMClient client = new AVIMClient("GuanYu");//刘备用自己的名字作为 ClientId。
    await client.ConnectAsync();
    client.OnMessageReceieved += (s, e) =>
    {
        if (e.Message is AVIMTextMessage)
        {
            string words = ((AVIMTextMessage)e.Message).TextContent;
            //words 的内容就是：曹操已对我起了疑心，我们还是赶紧跑路吧……
            NitifiedConversation = e.Conversation;
        }
    };
}
public async void SendToBoss()
{
    if (NitifiedConversation != null)
    {
        await NitifiedConversation.SendTextMessageAsync("大哥，莫怕！有我和三弟保护你!");
    }
}

而以上刘备和关羽发送的消息，张飞上线的时候都会收到。

对话的管理

以上 2 节基本演示了 V2 版本的实时聊天 SDK 的核心概念——AVIMConversation ，LeanCloud 将单聊和群聊（包括聊天室）的消息发送和接受都依托于 AVIMConversation这个统一的概念进行操作。

所以，开发者需要强化理解的一个概念就是：SDK 层面是不再区分单聊以及群聊。

对话的成员管理

对话的管理包括成员管理，属性管理两个方面。

首先来介绍对话的成员管理：

自身主动加入

许攸自袁绍出叛逃之后，主动跑到曹操帐中献技火烧乌巢，随即他想主动加入到曹操的「谋士群」中，以下代码将帮助他实现这个功能：

code

该群的其他成员（比如程昱）会根据自身客户端的状态不同会出现以下 2 种情况:

如果程昱仅仅是登陆了应用，并没有加载具体的对话到本地，他只会收到 AVIMClient.OnConversationMembersChanged 的响应的相关操作，代码如下:

code

如果程昱不但登陆了，还在客户端加载了当前这个对话，那么他不但会收到 AVIMClient.OnConversationMembersChanged 的响应的相关操作，也会收到 AVIMConversation.OnMembersJoined 的响应的相关操作，代码如下：

code

添加其他成员

话说曹操接受关羽的「降汉不降曹」之后，曹操想把关羽拉到自己的「武将群」中，需要如下代码帮助他实现这个功能：

code

该群的其他成员（例如张辽）也会受到该项操作的影响，收到事件被响应的通知，类似于第一小节自身主动加入中**许攸加入「谋士群」之后，程昱受到的影响 **

自身退出对话

这里一定要区分自身退出对话的主动性，它与自身被动被剔除（下一小节）在逻辑上完全是不一样的。

又说刘备看到袁绍的刚愎自用之后，借机从袁绍处脱身自救，他离开袁绍的势力范围之后，主动从袁绍的「谋士群」中退出，他需要如下代码实现需求：

code

该群的其他成员（例如沮授）也会受到该项操作的影响，收到事件被响应的通知，类似于第一小节自身主动加入中**许攸加入「谋士群」之后，程昱受到的影响 **

剔除其他成员

关羽过五关斩六将之后，曹操还是不忍心把关羽从武将群里面删除，曹操的高级秘书程昱行使了管理员的权限把关羽从群组中剔除，以安抚夏侯惇等一众武将。
注：关于程昱如何获得管理员权限在后面的签名和安全一章节会做详细阐述，此处不宜扩大话题范围）

以下代码可以帮助程昱实现这一功能：

code

对话的属性管理

对话（AVIMConversation）与控制台中 _Conversation 表是一一对应的，属性对应的关系如下：

AVIMConversation.ConversationId = _Conversation.objectId//全局唯一的 Id
AVIMConversation.Name = _Conversation.name//成员共享的统一的名字
AVIMConversation.MemberIds = _Conversation.m//成员列表
AVIMConversation.MuteMemberIds = _Conversation.mu//静音成员列表
AVIMConversation.Creator = _Conversation.c//对话创建者
AVIMConversation.LastMesaageAt = _Conversation.lm//对话最后一条消息发送的时间
AVIMConversation.Attributes = _Conversation.attr//自定义属性

名称

这个属性是全员共享的一个属性，他可以在创建时指定，也可以在日后的维护中被修改。

诸葛亮躬耕南阳之时，常与荆湘地带的名流雅士在一起谈论天下大事，水镜先生就建立了一个群，把庞统，徐庶等人一并拉入。

水镜先生需要写的代码如下：

code

曹丕登基之后，把文武百官所在的群「汉」的名字改成了「魏」，他需要如下代码：

code

成员

该属性表示当前对话中所包含的成员的 clientId ，这个属性强烈建议开发者切勿在控制台中随意修改，所有关于成员的操作请参照上一章节中的 成员管理 来进行。

静音成员

假如某一个用户不想再收到某对话的消息，又想直接退出对话，可以使用静音操作。

徐庶被曹操设计骗到了曹操的势力范围，母亲因此愤而投井自杀，徐庶心生悲痛，深知此生曹操是不会放他走的，所以他决定此生不为曹操出谋划策，所以当曹操把他拉入到「谋士群」之后，徐庶聪明地选择了对该群静音：

code

此属性也强烈建议开发者切勿在控制台中随意修改。

创建者

对话的创建者可以帮助实现类似于 QQ 群中区别管理员和群所有者，它的值是对话创建者的 clientId。

code

自定义属性

此属性是为了帮助开发者给对话添加自定义属性。

曹操发现自己加入的对话太多了，有包含曹氏一族，夏侯一族的「兄弟群」，有包含曹丕，曹植诸多儿女的「孩子群」，又有「武将群」，「谋士群」等等等等，他需要一个简单的标识来区分这些群，这时他想起了 AVIMConversation.Attributes 的自定义的特性，所以他给「兄弟群」以及「孩子群」添加了一个 family 的自定义属性，为「武将群」，「谋士群」添加一个 work 的自定义属性，于是曹操挥笔写下了如下代码：

code

注意：AVIMConversation.Attributes 在 SDK 级别是对所有成员可见的，如果要控制所谓的可见性，开发者需要自己维护这一属性的读取权限

AVIMConversation.Attributes 在对话查询一节还有更多的用法。

富媒体消息

富媒体消息的支持是 V2 版本针对 V1 的一个核心提升，我们目前 SDK 已经支持的富媒体消息类型有以下几种：

图片消息：AVIMImageMessage
音频消息：AVIMAudioMessage
视频消息：AVIMVideoMessage
文件消息：AVIMFileMessage
地理位置消息：AVIMLocationMessage

图片消息

发送图片消息

曹操拿下官渡之战，灭掉乌桓，挥师南下，意在江东，蔡瑁挟荆州众将举城归降，曹操信心爆棚，拿出手机拍了一张城楼上鸟瞰荆州的照片，发给了镇守许昌的荀彧，说罢就写下了如下代码：

code

接受图片消息

音频消息

发送音频消息

照片发完之后，曹操紧接着录了一段录音发给了孙权「仲谋啊，我与令尊同生共死于讨伐董卓之时，遥想彼时已历十八载，今我挟天子之师，意在不臣，望君切勿放纵玄德等一干佞臣」，身旁的高级秘书程昱赶忙书写了以下代码：

code

接受音频消息

视频消息

发送视频消息

周瑜黄盖实施苦肉计之时，诈降而来的蔡瑁弟弟蔡中，拿出手机偷拍了全部过程，特地回发给了曹操，曹操看到视频之后，更加坚信黄盖是真心归降。蔡中要发送视频需要如书写代码：

code

接受视频消息

文件消息

庞统献计铁索连环之后，便偷偷记录下了连船之后的部署图，用加密算法压缩之后，发送给诸葛亮，庞统半夜挑灯写下了如下代码：

创建文件消息

code

发送文件消息

接受文件消息

地理位置消息

曹操赤壁大败之后，想发送自己的地理位置给后方驻守的部队，通知他们前来救驾，他命谋士写下如下代码：

code

发送地理位置消息

对话的查询

基础查询

假如已知某一对话的 Id，可以利用查询该对话的详细信息
郭嘉病逝，赤壁大败，曹操深感受挫，他需要更多的帮手，这个时候，他想起可以搜索附近的人或者根据某些特殊字符可以搜索到他想要的文臣武将，于是他下令写下了如下代码：

code

Windows Phone 实时通信服务(v2)

简介

安装

初始化

单聊

发送消息

接受消息

群聊

发送消息

接受消息

对话的管理

对话的成员管理

自身主动加入

添加其他成员

自身退出对话

剔除其他成员

对话的属性管理

名称

成员

静音成员

创建者

自定义属性

富媒体消息

图片消息

发送图片消息

接受图片消息

音频消息

发送音频消息

接受音频消息

视频消息

发送视频消息

接受视频消息

文件消息

创建文件消息

发送文件消息

接受文件消息

地理位置消息

发送地理位置消息

发送地理位置消息

对话的查询

基础查询

条件查询

匹配查询

计数查询

开放聊天室

创建开放聊天室

查询在线人数

聊天记录

聊天记录获取

聊天记录限制

签名与安全

签名的概念

签名示例

内容目录

选择主题