gloox 获取花名册和联系人出席信息

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