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( "[email protected]/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

傳回目前狀态資訊

傳回值：

    目前狀态資訊