smack3.x API

Smack文档（翻译）

 

Contents:

• 概要
• 入门指南
• 管理连接
• 信息基础
• 角色与状态
• 处理数据包
• 服务架构
• 包属性
• 调试Smack
• 隐匿
• Smack扩展手册

概要：

Smack 是一个与XMPP服务器进行实时通讯的客户端库，包括即时信息与聊天组。

Smack优势：

 

• 易于使用，且功能强大的API。与用户通讯可以在只有几行代码
• 

  View Code

  

  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类是用来创建一个到服务器连接。下面是示例代码：

View Code

// 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），

聊天、群聊等，提供了更高层次的结构，自动管理创建和发送数据，你也可以直接创建和发送数据包。下面是一个代码示例来改变你的存在，让人们知道不可用与离线。

View Code

// 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]" 在例子中).

连接和断开

View Code

// 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）。下面的代码段演示如何创建一个新的用户聊天，然后发送文本消息：

View Code

// 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) 方法，如下面的代码片段：

View Code

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

上面的例子中，我们指定一个messagelistener当创建一个Chat。监听器随时更新聊天记录，下面代码使用一个监听器作为parrot-bo

View Code

 // 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你必须注册并通知它，你可以注册消息监听器来接受信息并处理。

View Code

// 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.

角色与状态：