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( )
应用中的花名册条目改动同步地反映到服务器