gloox 之 Client

Client 类，实现了一个基本的Jabber客户端，派生自 ClientBase类

详细说明：
此类实现了一个基本的Jabber客户端
它支持SASL Authentication （SASL验证）以及TLS（加密），都是分别自动切换 "启用或关闭" 状态的。
如果服务器支持，它们就会被自动地启用。

使用方法：创建一个Client类对象，传入连接验证信息(Jid,密码)，验证信息在构造时传入或之后Set进去都是可以的。
然后你应该为实现各自的接口注册对应的处理器。
（ConnectionListener，PresenceHandler，MessageHandler，IqHandler，SubscriptionHandler等处理器）
调用connect()连接到服务器。
注意：
   虽然MessageHandler接口仍然有效（在以后的版本中也有效），但是建议在严肃的消息传送上使用新类MessageSession。
简单示例：
 using namespace gloox;

 void TestProg::doIt()
 {
   Client* j = new Client( "user@server/resource", "password" );
   j->registerPresenceHandler( this );                     //可以看出TestProg类，继承了PresenceHandler类或它的派生类
   j->disco()->setVersion( "TestProg", "1.0" );
   j->disco()->setIdentity( "client", "bot" );
   j->connect();
 }

 virtual void TestProg::handlePresence( Stanza *stanza )
 {
   // handle incoming presence packets here
 }

然而，如果你启用了RosterManager，你可以跳过出席处理的步骤。
默认情况，gloox库为了应用程序的考虑，会处理几个IQ名空间里节（从服务器发来），这些包括：
1、jabber:iq:roster  默认情况，服务器端的花名册被取出和处理。利用rosterManager()函数和RosterManager类对Roster进行操作。
2、XEP-0092（软件版本）：如果没有明确指定版本号，那么就以字符串“based on gloox”为gloox库的当前版本发布出去。
3、XEP-0030（服务发现）：所有被支持或有效的服务被发布。没有任何返回事项。
注意：
    1、gloox 0.9版，默认情况，延承初始出席的优先权，是0.
    2、gloox 0.9版，初始出席被自动发送。即 出席：有效，优选权值：0。欲使初始出度无效，则在连接之前调用setPresence()，并传入
       值为PresenceUnavailable的参数，即可。
SASL Authentication （SASL验证）
另外，相对于简单的基于IQ的验证（XEP-0078），gloox提供几种SASL验证机制。
1、DIGEST-MD5：如果帐号和密码都在Client对象中提供了，这种机制是首选，即使没有TLS加密也是安全的。
2、PLAIN：如果DIGEST-MD5无效，就使用此种机制。在没有TLS加密时是不安全的。
3、ANONYMOUS：此种机制在没有提供帐号和密码时使用。服务器将随机产生临时帐号和资源，提供限制的有效服务。
4、EXTERNAL：此种机制目前只对客户端提供了证书和保密关键字（private key）而有效，服务器试图通过外部计算出客户端。举例来说，使用提供

的证书或IP地址。（在将来将提高证书/关键字有效性的限制）
当然，这些机制都不可靠，除非服务器提供它们。

 

Client (const std::string &server)
构造一个只能用来注册新帐户的Client对象。SASL 和 TLS 默认下己经开启，通过查找服务记录端口将被限制。
作为替代，你也可以显示调用setPort来指定端口。
参数：server 将要连接到的服务器

 

Client (const JID &   jid,
 const std::string &   password,
 int     port = -1
 ) 
构造一个Client对象。SASL 和 TLS 己经开启（默认）。此构造函数会被多数客户端当作默认构造函数使用。服务器地址将在提供的JID中得到。
实际主机将通过服务记录确定。JID的域名部分在没有找到服务记录时被用作后备，或者你可以调用setServer()函数另外设置服务器地址。
参数:
     username  JID帐号服务器之前的部分.
     resource  JID的资源.
     password  帐号认证的密码
     server          JID的服务器部分或将要连接到的主机名。如果它们不相同，将使用第二个
     port          将要连接到服务器端口，默认－1，意思是经过DNS服务查找。

 

void addPresenceExtension ( StanzaExtension * se)
使用此函数你可以添加一个随每个任何出席节一起发送的StanzaExtension类对象（即扩展节）。用例包含以下，签名的出席（GPGSigned，XEP-0027

），VCard是通告的具体实现（VCardUpdate XEP-0153），和其它（参阅StanzaExtension的派生类）
参数：
   se   加入的StanzaExtension 对象。Client对象成为传入的StanzaExtension的宿主。
注意：
   目前没有办法选择地删除一个扩展。调用removePresenceExtensions() 将删除全部的扩展。

 

 

void bindResource ( )
在程序调用ConnectionListener::onResourceBindError()，通知你程序绑定资源错误时，你可以调用此函数被将重新试图绑定一个资源。
你也许（或应该）在发生这种事情之前在程序的某个地方调用setResource()函数。

 

 

void disableRoster()
此函数使花名册的自动管理无效。之后，如果你想拥有一个花名册，不得不自己追踪每个到达的出席信息。

 

 

void disconnect()
断开与服务器的连接

 

 

bool login()
初始化一个登录尝试（目前 不支持 SASL扩展）。这对于注册一个新帐号之后比较有用（方便）。

简简单单地调用setUserName()和setPassword()然后调用 login()。

（我的理解，在客户端程序中，注册一个新帐号后，不用退出程序，直接调用login()直接实现登录）。
返回值：
   true  说明登录尝试被成功开启，否则返回false。返回值不能表明登录成功，只是表明登录尝试被成功发起。

 

void nonSaslLogin() [ protected 成员函数]
初始化 非SASL登录

 

 

Presence presence() const
返回当前的出席

 

 

int priority()const
返回当前优先权

 

 

void removePresenceExtensions()
删除由addPresenceExtension()函数添加的所有扩展

 

 

const std::string& resource() const
返回当前己准备的资源

 

 

RoserManager* rosterManager()
此函数返回一个指向RosterManager对象的指针。

 

 

GLOOX_DEPRECATED void setForceNonSasl(bool force=true)
这是一个暂时强制使用非SASL登录(Non-SASL login )的方法。你不需要使用它
参数：
   force   确定是否强制Non-SASL验证。默认值为true。
反对：请更改服务器适当地支持SASL连接作为代替

 

 

void setPresence(Presence              presence,
                 int                   priority = 0,
                 const std::string &   msg=""
)
用来设置实体的出席。如果在建立连接之前调用，那么设定值就会与初始出席一起发送。如果连接建立之后调用，出席会立刻被发送出去。
参数：
   presence   设定的Presence值
   priority   （可选）一个可选的优先值。正当值为： －128<=priority<=127
   msg        （可选）出席状态的描述信息
从0.9 版本支持

 

 

void setResource (const std::string& resouce)
设定用于连接到XMPP服务器的资源
参数：
   resource   用来登录进服务器的资源

 

 

void setUsername( const std::string& username)
设定用于连接到XMPP服务器的帐号
参数：
   username  用来进行身份验证的用户帐号

 

 

const std::string& status()const
返回当前状态信息
返回值：
    当前状态信息