gloox 之 RosterManager
此类实现了jabber:iq:roster名空间中的Jabber/XMPP花名册操作
它继承了 IqHandler, PresenceHandler,SubscriptionHandler 和 PrivateXMLHandler
详细说明：
此类实现了jabber:iq: roster名空间中的Jabber/XMPP花名册操作。
它管理着出席，订阅的变更等等 。你可以在任何时间改动花名册中的名册条目项。这些改动必须通过调用synchronize()函数与服务器同步。
注意：到达的花名册中条目初始值可能会被其它资源重写而改变。另外XEP-0083（花名册的组管理）也在此处实现了。
构造与析构函数
RosterManager( ClientBase * parent )
构造一个新的RosterManager对象。
参数： parent 一个用来通信的ClientBase对象
~RosterManager() (虚函数)
成员函数
void handleSubscription( Stanza* stanza )
重新实现此函数， 当多个订阅/一个订阅请求到达时，应用得到通知。
须实现SubscriptionHandler接口
void ackSubscriptionRequest( const JID & to, bool ack )
如果你被要求异步处理订阅请求，你可以使用此函数回复一个订阅请求
参数：
to 被回复的JID( 即同意或拒绝 此JID的订阅请求)
ack 是否同意/拒绝上述联系人的订阅请求
void subscribe ( const JID& jid,
const std::string& name="",
const StringList& groups=StringList(),
const std::string& msg=""
)
使用此函数订阅一个新的联系人。此联系人会被自动地加入花名册（符合RFC 3921 的服务器 ）。
参数：
jid 要订阅的联系人jid
name 联系人的显示名称
groups 联系人所属的组列表
msg 同订阅请求一起发送的文本
void unsubscribe( const JID& jid,
const std::string& msg=""
)
使用此函数取消对一个联系人的订阅。你将不再收到此联系人的出席信息。
注意：
remove()函数从花名册中移除一个联系人并且取消了对此联系人的订阅。
void cancel( const JID& jid,
const std::string& msg=""
)
使用此函数取消一个联系人对你出席的订阅。联系人将不会再从你那里收到出席信息。
参数：
jid 联系人的JID
msg 同取消请求一起发送的文本内容。
注意：
使用remove() 从花名册中移除一个联系人并且取消对此联系人的订阅。
void remove( const JID& jid )
使用此函数从花名册中除一个联系人，并且对于此联系人的订阅也会被取消。
参数： jid 联系人的JID
void add( const JID & jid,
const std::string& name,
const StringList& groups
)
使用此函数向花名册中添加一个联系人。不会发送订阅请求。
注意： 使用 unsubscribe()从花名册中移除一个条目。
参数：
jid 将要添加联系人的JID
name 联系人外部显示的名称
groups 联系人所属的组列表（译注：一个联系人，可以属于多个组）
const std::string& delimiter( ) const
使用此函数检索嵌套花名册组的分隔符（XEP-0083），返回组分隔符
void fill()
此函数用当前服务端的花名册初始化应用的花名册
RosterItem* getRosterItem( const JID& jid )
通过此函数你可以获取指定JID的花名册条目
参数： jid 将要获取的花名册条目所属的JID
bool handleIq( Stanza* stanza ) (虚函数)
重写此函数，当IQ节到达时，你将会得到通知
参数： stanza 完整节
返回值： 表明一个get 或set 类型的请求是否己经被处理。包含必须的result回复。如果你返回了false,一个error将被发送出去。
须实现 IqHandler接口
bool handleIqID( Stanza* stanza,
int context
) (虚函数)
实现此函数，你可以接收到指定id属性值的IQ节的到达通知。你必须使用Client::trackID()跟踪这些id。这对那些产生一个明确应答的那些id比较有用。
例如：名空间过滤器不能工作时的<iq type='result' id='reg'/>
参数：
stanza 完整节。
context 用来复原上下文的一个值。与ClientBase::trackID()储存在一起。
返回值：表明一个get 或set 类型的请求是否己经被处理。包含必须的result回复。如果你返回了false,一个error将被发送出去。
须实现 IqHandler接口
void handlePresence( Stanza* stanza )
重写此函数你可以在出席通知到达时进行一些更新操作。
void handlePrivateXML( const std::string& tag,
Tag* xml
)
重新实现此函数，可以接收早些时候调用PrivateXML::requestXML()函数请求的隐蔽的XML数据
参数：
tag 标签的数据包
xml 隐蔽的xml数据。例如：<query>标签的第一个子标签。
须实现PrivateXMLHandler接口
void handlePrivateXMLResult( const std::string& uid,
PrivateXMLResult pxResult,
) (虚函数)
此函数被调用，用来通知一个store或request操作的结果（凭借（利用）handlePrivateXML()函数，成功的请求被宣布。）
参数：
uid 请求的ID
pxResult 操作的结果
须实现PrivateXMLHandler接口
void registerRosterListener( RosterListener* rl,
bool syncSubscribeReq = true
)
注册一个RosterListener对象用来接收花名册的更新信息。对应用的图形界面来说，这比较有用，当我们需要显示一个对话框或用其它方式显示的时候，不想被被阻塞，那么我们可以使用异步的订阅请求。如果我们想立即应答一个请求，那么就使用同步的方式。
参数：
rl 负责接收花名册更新的对象
syncSubscribeReq 表示订阅（取消）请求应该被异步（false）或同步(true)的处理。默认：同步。
void removeRosterListener( )
移除当前的RosterListener对象，花名册的所有事件将不会在任何地方被接收。
Roster* roster()
返回一个花名册，实际是一个<JID，出席> map结构。
void setDelimiter( const std::string& delimiter )
使用此函数设定组的分隔符（XEP-0083）
void synchronize( )
应用中的花名册条目改动同步地反映到服务器
原文地址：http://blog.csdn.net/night_cat/article/details/4284536
------------------------------------------------------------------------------------------------------------------
RFC6121 http://wiki.jabbercn.org/RFC6121#.E5.87.BA.E5.B8.AD.E4.BF.A1.E6.81.AF.E5.8E.9F.E7.90.86
本文内容由网友自发贡献，版权归原作者所有，本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容，请联系:hwhale#tublm.com(使用前将#替换为@)
