Smack文檔（翻譯）

Contents:

• 概要
• 入門指南
• 管理連接
• 信息基礎
• 角色與狀態
• 處理數據包
• 服務架構
• 包屬性
• 調試Smack
• 隱匿
• Smack擴展手冊

概要：

Smack 是一個與XMPP服務器進行實時通訊的客戶端庫，包括即時信息與聊天組。

Smack優勢：

 

• 易於使用，且功能強大的API。與用戶通訊可以在只有幾行代碼

• Connection connection = new XMPPConnection("jabber.org");
  connection.connect();
  connection.login("mtucker", "password");
  Chat chat = connection.getChatManager().createChat("[e-mail]", new MessageListener() {
  
      public void processMessage(Chat chat, Message message) {
          System.out.println("Received message: " + message);
      }
  });
  chat.sendMessage("Howdy!");

• 像其他類庫中一樣，不強迫你在包中編碼，提供了更智能的結構如 Chat 與 Roster類，讓你的程序更有效。
• 不需要你熟悉XML格式

• 提供簡單的點對點通信。Smack可以在每個消息中設置一些的屬性，包括屬性，對象。

• 開放源碼，這意味着你可以將它用到你的商業或非商業應用中。
  
  

關於XMPP

XMPP（可擴展消息存在協議）是一個開放的協議標准，並支持和擴展的協議標准基礎（（譯：//www.xmpp的。）。

如何使用本文檔

 

假設你已經熟悉即時通訊的主要特點。那么也強烈建議你打開文檔程序指南和使用作為參考，通過閱讀本文檔。

入門指南：

本文檔將向你介紹和提供了一個重要的類別和概念

所需的JAR文件

Smack可以很方便的在JDK1.5或更高版本的應用中使用，它不依賴外部包（除語音聊天），並且盡可能小，庫文件提供更多的靈活性和功能應用要求：

• smack.jar -- 提供核心的功能，是必須的庫。所有的功能的一部分，包括協議。
• smackx.jar --在標准基礎上支持更多的擴展（xeps）定義，包括多用戶聊天，文件傳輸，用戶搜索，等擴展記錄。
• smackx-debug.jar --增強的圖形用戶界面的調試協議。當啟用了調試，它會自動發現路徑。

建立一個連接

該xmppconnection類是用來創建一個到服務器連接。下面是示例代碼：

// Create a connection to the jabber.org server.
Connection conn1 = new XMPPConnection("jabber.org");
conn1.connect();

// Create a connection to the jabber.org server on a specific port.
ConnectionConfiguration config = new ConnectionConfiguration("jabber.org", 5222);
Connection conn2 = new XMPPConnection(config);
conn2.connect();

注意，使用到服務器的默認安全連接連接（可能時），包括使用協議加密。該connectionconfiguration類提供了先進的控制建立連接與連接管理詳細，如能夠禁用或要求加密。

一旦創建了連接，你可以使用用戶名和密碼登陸連接。登錄（字符串用戶名，密碼）方法。一旦登錄后，你可以與其他用戶創建的對象或群聊天。

名冊Roster工作

Roster可以讓你跟蹤存在的其他用戶。用戶可以組織成組如“朋友”和“同事”，然后你可以發現每個用戶是否在線或離線。

getroster()方法獲得名冊連接。Roster類可以讓你找到所有Roster實體，他們所屬的群體，和目前每個實體的存在狀態。

讀取和寫入數據包

每個到XMPP服務器的消息從客戶端被稱為數據包和發送數據。org.jivesoftware.smack.packet包中包含封裝的三種不同的基本類型所允許的類（message, presence, and IQ），

聊天、群聊等，提供了更高層次的結構，自動管理創建和發送數據，你也可以直接創建和發送數據包。下面是一個代碼示例來改變你的存在，讓人們知道不可用與離線。

// Create a new presence. Pass in false to indicate we're unavailable.
Presence presence = new Presence(Presence.Type.unavailable);
presence.setStatus("Gone fishing");
// Send the packet (assume we have a Connection instance called "con").
con.sendPacket(presence);

Smack提供2種不同方式讀取傳入的數據包，PacketListener,  PacketCollector,以及packetfilter的使用情況，確定哪些數據包應處理。一個數據包偵聽器在不同的編程中使用。你可以投遞和禁止操作結果隊列中的信息包收集器。因此，當傳遞信息包或者等待特定的數據包，包收集器也是非常有用的 。包監聽器以及收集器可以在一個連接中被創建。

管理連接：
 org.jivesoftware.smack.Connection 類提供了到XMPP服務器的連接管理。默認實現的是 org.jivesoftware.smack.XMPPConnection類.有2個主要構造函數，一個是XMPPConnection(String)

連接參數為服務器名稱。將使用所有默認連接設置：

• DNS查找到確切的服務器駐留地址和端口（一般為5222）

• 如果有必要，設置服務器協商協議，包括加密的安全性，但連接將回到較低的安全設置。

• 名為"Smack" 的XMPP 資源將用於連接。

另外，您可以使用xmppserver（connectionconfiguration）構造函數指定連接設置。這些設置包括：

• 手動指定服務器地址和端口的服務器，而不是使用DNS查找。

• 啟用連接壓縮

• 自定義安全設置，如標記連接要求和加密連接點。

• 指定一個連接資源名稱如 "Work" 或 "Home".每個到服務器連接的用戶必須有一個獨特的資源名稱。. 用戶 "[e-mail]", 詳細資源地址可能是"[e-mail]/Smack". 作為唯一的資源名,用戶可以從多個地點或使用多個設備，登錄到服務器。優先級值與每個資源將確定哪些特定的連接接收郵件地址("[e-mail]" 在例子中).

連接和斷開

// Create the configuration for this new connection
ConnectionConfiguration config = new ConnectionConfiguration("jabber.org", 5222);
config.setCompressionEnabled(true);
config.setSASLAuthenticationEnabled(true);

Connection connection = new XMPPConnection(config);
// Connect to the server
connection.connect();
// Log into the server
connection.login("username", "password", "SomeResource");
....
// Disconnect from the server
connection.disconnect();

使用 ConnectionConfiguration#setReconnectionAllowed(boolean) 來開關這種特性，將默認重新嘗試連接以防突然斷開。重新連接管理將立刻連接到服務器和在嘗試連接失敗時增加延遲。

如果你想重新等待下一個連接，你可以使用 Connection#connect()一個新的嘗試將被建立。如果手動嘗試也沒有用，那么連接管理器將繼續連接工作。
信息基礎：

即時通訊的核心是來回發送消息，雖然個別郵件可以來回發送消息包，但一般容易處理的字符串信息聊天是使用org.jivesoftware.smack.chat類。

Chat

一個聊天對應創建新線程的消息（使用一個線程ID）。下面的代碼段演示如何創建一個新的用戶聊天，然后發送文本消息：

// Assume we've created a Connection name "connection".
ChatManager chatmanager = connection.getChatManager();
Chat newChat = chatmanager.createChat("[e-mail]", new MessageListener() {
    public void processMessage(Chat chat, Message message) {
        System.out.println("Received message: " + message);
    }
});

try {
    newChat.sendMessage("Howdy!");
}
catch (XMPPException e) {
    System.out.println("Error Delivering block");
}

Chat。發（字符串）方法是一種方便的方法，創建一個消息對象，設置body使用字符串參數來發送消息，在這種情況下，使用Chat.createMessage() 與 Chat.sendMessage(Message) 方法，如下面的代碼片段：

Message newMessage = new Message();
newMessage.setBody("Howdy!");
message.setProperty("favoriteColor", "red");
newChat.sendMessage(newMessage);

上面的例子中，我們指定一個messagelistener當創建一個Chat。監聽器隨時更新聊天記錄，下面代碼使用一個監聽器作為parrot-bo

 // Assume a MessageListener we've setup with a chat.

    public void processMessage(Chat chat, Message message) {
        // Send back the same text the other user sent us.
        chat.sendMessage(message.getBody());
    }

Incoming Chat

聊天是由另一個用戶發起，你開始接收聊天訊息，如不是顯式創建一個聊天或發送郵件，您需要創建並注冊chatmanager chat實例。

該chatmanager已經找到一個匹配的聊天（線程ID），如果不存在它將創建一個新的來匹配。這個新的Chat你必須注冊並通知它，你可以注冊消息監聽器來接受信息並處理。

// Assume we've created a Connection name "connection".
ChatManager chatmanager = connection.getChatManager().addChatListener(
    new ChatManagerListener() {
        @Override
        public void chatCreated(Chat chat, boolean createdLocally)
        {
            if (!createdLocally)
                chat.addMessageListener(new MyNewMessageListener());;
        }
    });

除了基於線程的聊天信息，有一些客戶不發送一個線程的一部分，處理這種情況，正好將嘗試匹配傳入的消息，找到最適合現有的Chat，基於JID。它會嘗試找到一個相同的全JID，如果沒有找到，則會使用基本的JID，如果沒有發現新的，用戶可以創建新的Chat.

角色與狀態：