花名册管理之基本概念和操作

这几天公司软件要增加黑名单的功能，因为公司产品的IM功能模块用的是开源的Gloox库，Gloox是实现了XMPP协议的c++客户端库，所以我觉得这个功能应该是很简单的，结果做起来发现XMPP的花名册管理（XMPP协议里面花名册管理部分相当于一般IM的好友管理）还挺麻烦的，消息绕来绕去的，我头都转晕了，再加上公司的前辈也没留下文档，没办法只有好好看看XMPP协议文档对花名册管理部分的描述了。
XMPP协议文档编号是RFC2193，里面的第7部分就是花名册管理（RostorManage）的描述，由于是英文文档，所以我看的速度很慢，然后边看边写了个Demo来印证，当然了Demo也是基于Gloox库的，服务端用的Openfire Server。花了一天的功夫终于有了个初步的了解，为了加深理解，也方便自己以后查阅，我决定把英文文档中关于RostorManage的部分翻译过来，然后加上一些自己的理解，下面就进入正题了。
在XMPP里面，一个人的联系人列表被称作一张花名册，其中包含一定数量联系人的名片，每张名片由JID唯一标识（JID通常是contact@domain的格式）。每个用户的花名册都被用户服务端存储在该用户的专属空间，所以该用户下的任意资源都可以访问花名册信息。
语法和语义
花名册通过包含一个<query/>子节点元素的IQ节点来管理花名册，并且这个子节点名为’jabber:iq:roster’域，这个<query/元素可以包含一个或者多个<item/>子元素，每个<item/>用来描述一个唯一的名片或者是联系人，每个<item/>包含一个JID作为关键字。在<item/>中可能会包含一个’subscription’属性，用来描述当前JID用户对于<item/>中的JID联系人用户出席订阅的状态，这个状态属性包含以下的值：
"none" -- 用户没有对联系人出席信息的一个订阅，同时联系人也没有对用户出席信息的订阅。
"to" --  用户有对联系人出席信息的一个订阅，但是联系人也没有对用户出席信息的订阅。
"from" -- 联系人有对用户出席信息的订阅，但是用户没有对联系人出席信息的订阅。
"both" -- 用户和联系人都要对彼此出席信息的订阅。
每个<item/>可以包含一个或者多个<group/>子节点，这些是用户用来将联系人分入不同的类别，比如我们可以将QQ好友分为同学类别、亲人类别或者是普通好友类别。每个<group/>节点之间都是分离的。
PS：最近发现网上早就有一个关于Jabber/XMPP协议的中文翻译计划的项目可扩展的消息和出席信息协议 (XMPP): 即时消息和出席信息，这个里面对整个RFC3921用完整的翻译，所以在此我也没有必要完全将整个RostorManage部分完全翻译出来，我就主要将自己的一些理解概括出来。
下面介绍一下RostorManage的关键点：
1）添加一个花名册子项
一个用户在任何时刻都可以添加一个子项到他（她）的花名册里面，如下，客户端添加一个新的花名册子项：
<iq from=’juliet@example.com/balcony’ type=’set’ id=’roster_2’>
<query xmlns=’jabber:iq:roster’>
<item jid=’nurse@example.com’
name=’Nurse’>
<group>Servants</group>
</item>
</query>
</iq> 服务端收到客户端发的添加信息后，必须用户的花名册信息，并永久保存，同时还要花名册的改变发送给当前用户下的所有要求传送花名册的资源，同时会要求客户端返回收到改变信息的回复消息。这个发送改变命令的格式如下：
<iq to=’juliet@example.com/balcony’
type=’set’
id=’a78b4q6ha463’>
<query xmlns=’jabber:iq:roster’>
<item jid=’nurse@example.com’
name=’Nurse’
subscription=’none’>
<group>Servants</group>
</item>
</query>
</iq>
<iq to=’juliet@example.com/chamber’
type=’set’
id=’a78b4q6ha464’>
<query xmlns=’jabber:iq:roster’>
<item jid=’nurse@example.com’
name=’Nurse’
subscription=’none’>
<group>Servants</group>
</item>
</query>
</iq>
服务端要求回复信息格式
<iq to=’juliet@example.com/balcony’ type=’result’ id=’roster_2’/>
上面“juliet@example.com“用户包含了两个资源”balcony“和”chamber“，客户端的用户资源在收到服务端发的信息后需要回复，格式如下：
<iq from=’juliet@example.com/balcony’
to=’example.com’
type=’result’
id=’a78b4q6ha463’/>
<iq from=’juliet@example.com/chamber’
to=’example.com’
type=’result’
id=’a78b4q6ha464’/>
2)更新一个花名册子项
更新的花名册的发送的数据格式和添加一个新的花名册一样，服务端收到更新消息后会永久的更新花名册的信息，同时将要更新的花名册子项发送给所有要请求花名册的用户资源，消息格式（客户端发送的一个更新花名册子项的分组的格式）如下：
<iq from=’juliet@example.com/chamber’ type=’set’ id=’roster_3’>
<query xmlns=’jabber:iq:roster’>
<item jid=’romeo@example.net’
name=’Romeo’
subscription=’both’>
<group>Friends</group>
<group>Lovers</group>
</item>
</query>
</iq>
3）删除一个花名册子项
用户可以再任意时刻从他（她）的花名册删除一个子项，通过发送一个IQ的SET消息给服务端，同时设置IQ节点’subscription’属性的值为”remove“（一个兼容性好的服务器会忽略这个属性的其他值），消息格式如下：
<iq from=’juliet@example.com/balcony’ type=’set’ id=’roster_4’>
<query xmlns=’jabber:iq:roster’>
<item jid=’nurse@example.com’ subscription=’remove’/>
</query>
</iq>
下面的内容是关于名册条目和出席信息订阅的集成，关于这一部分内容比较长，细节也比复杂，所以我决定主要是图表的方式描述，再附带说明，就留着下一节介绍。