====== 创建和管理聊天室 ======

本文介绍如何创建和管理聊天室。

===== 技术原理 =====

环信即时通讯 IM SDK 提供 ''%%EMChatRoomManager%%'' 类 和 ''%%EMChatRoom%%'' 类，支持聊天室的创建、获取、修改、删除等管理功能。主要方法如下：

  * ''%%fetchPublicChatRoomsFromServer%%'' 从服务器获取指定数目的聊天室;
  * ''%%createChatRoom%%'' 创建聊天室;
  * ''%%fetchChatRoomFromServer%%'' 获取聊天室实例;
  * ''%%joinChatRoom%%'' 加入聊天室;
  * ''%%leaveChatRoom%%'' 退出聊天室；
  * ''%%destroyChatRoom%%'' 解散聊天室。

===== 前提条件 =====

开始前，请确保满足以下条件：

  * 完成 SDK 初始化，详见 [[ccim:android:quickstart|快速开始]]。
  * 了解环信即时通讯 IM 的限制条件，详见 [[ccim:limitation|限制条件]]。
  * 了解环信即时通讯 IM 聊天室不同版本的数量限制，详见 [[https://www.easemob.com/pricing/im|环信即时通讯 IM 价格]]。
  * 聊天室创建者和管理员的数量之和不能超过 100 ，即管理员最多可添加 99 个。

===== 实现方法 =====

==== 从服务器获取指定数目的聊天室 ====

用户调用 ''%%fetchPublicChatRoomsFromServer%%'' 接口可以从服务器获取指定数目的聊天室列表，''%%pageSize%%'' 最大值为 ''%%1,000%%''。

<code java>
// Asynchronous processing is required.
EMPageResult<EMChatRoom> chatRooms = EMClient.getInstance().chatroomManager().
                            fetchPublicChatRoomsFromServer(pageNumber, pageSize);
</code>

==== 创建聊天室 ====

用户可以调用 ''%%createChatRoom%%'' 接口创建聊天室。

示例代码如下：

<code java>
// Asynchronous processing is required.
EMChatRoom  chatRoom = EMClient.getInstance().chatroomManager().createChatRoom(subject, description, welcomMessage, maxUserCount, members);
</code>

==== 获取聊天室实例 ====

用户可调用 ''%%fetchChatRoomFromServer%%'' 获取聊天室的基本信息。

示例代码如下：

<code java>
// Asynchronous processing is required.
EMChatRoom chatRoom = EMClient.getInstance().chatroomManager().fetchChatRoomFromServer(chatRoomId);
</code>

==== 加入聊天室 ====

用户可调用 ''%%joinChatRoom%%'' 进入特定聊天室。

**注意**

  * 聊天室所有成员都有权限调用该方法。
  * 其他成员收到通知，触发其他成员的 ''%%onMemberJoined%%'' 回调方法。

示例代码如下：

<code java>
EMClient.getInstance().chatroomManager().joinChatRoom(chatRoomId, new EMValueCallBack<EMChatRoom>() {
    @Override
    public void onSuccess(EMChatRoom value) {

    }
   
    @Override
    public void onError(int error, String errorMsg) {
    
    }

});
</code>

==== 退出聊天室 ====

用户可以调用 ''%%leaveChatRoom%%'' 退出当前聊天室。

**注意**

  * 聊天室所有成员都有权限调用该方法。
  * 其他成员收到 ''%%onMemberExited%%'' 回调。

示例代码如下：

<code java>
EMClient.getInstance().chatroomManager().leaveChatRoom(chatRoomId);
</code>

==== 解散聊天室 ====

聊天室所有者可以调用 ''%%destroyChatRoom%%'' 解散聊天室。

**注意**

  * 聊天室所有成员都有权限调用该方法。
  * 其它成员会收到解散通知，并且被踢出聊天室，触发其他成员的 ''%%onChatRoomDestroyed%%'' 回调方法。

示例代码如下：

<code java>
// Asynchronous processing is required.
EMClient.getInstance().chatroomManager().destroyChatRoom(chatRoomId);
</code>

==== 离开聊天室保留本地消息 ====

离开聊天室时，SDK 默认会删除此聊天室本地所有消息，如果不想删除，可以设置 ''%%EMOptions#setDeleteMessagesAsExitChatRoom%%'' 为 ''%%fasle%%''。

示例代码如下：

<code java>
EMOptions options = new EMOptions();
options.setDeleteMessagesAsExitChatRoom(false);
</code>

==== 设置聊天室监听 ====

获取聊天室的变化，可以注册聊天室监听。

<code java>
// 注册聊天室回调。
EMClient.getInstance().chatroomManager().addChatRoomChangeListener(chatRoomChangeListener);
</code>

<code java>
// 移除聊天室回调。
EMClient.getInstance().chatroomManager().removeChatRoomListener(chatRoomChangeListener);
</code>

=== 聊天室监听方法 ===

<code java>
public interface EMChatRoomChangeListener {
    /**
     * 聊天室被解散。
     * @param roomId        聊天室 ID。
     * @param roomName      聊天室名称。
     */
    void onChatRoomDestroyed(final String roomId, final String roomName);

    /**
     * 聊天室加入新成员事件。
     * @param roomId        聊天室 ID。
     * @param participant   新成员 username。
     */
    void onMemberJoined(final String roomId, final String participant);
    
    /**
     * 聊天室成员主动退出事件。
     * @param roomId        聊天室 ID。
     * @param roomName      聊天室名称。
     * @param participant   退出的成员 ID。
      */
    void onMemberExited(final String roomId, final String roomName, final String participant);
    
    /**
     * 聊天室人员被移除。
     * @param reason        用户被移出聊天室的原因：
     *                        - xxx BE_KICKED：该用户被聊天室管理员移除；
     *                        - xxxBE_LICKED)FOR_OFFLINE：该用户由于当前设备断网被服务器移出聊天室。
     * @param roomId        聊天室 ID。
     * @param roomName      聊天室名称。
     * @param participant   被移除人员 ID。
     */
    void onRemovedFromChatRoom(final int reason, final String roomId, final String roomName, final String participant);
    
    /**
     * 有成员被禁言。
     * 禁言期间成员不能发送发消息。
     * @param chatRoomId    聊天室 ID。
     * @param mutes         禁言的成员。
     * @param expireTime    禁言有效期，单位为毫秒。
     */
    void onMuteListAdded(final String chatRoomId, final List<String> mutes, final long expireTime);
    
    /**
     * 有成员从禁言列表中移除。
     * @param chatRoomId    聊天室 ID。
     * @param mutes         移出禁言列表的成员名单。
     */
    void onMuteListRemoved(final String chatRoomId, final List<String> mutes);
    
    /**
     * 白名单成员增加。
     * @param chatRoomId    聊天室 ID。
     * @param whitelist     白名单中增加的成员名单。
     */
    void onWhiteListAdded(final String chatRoomId, final List<String> whitelist);
    
    /**
     * 白名单成员减少。
     * @param chatRoomId    聊天室 ID。
     * @param whitelist     白名单中移除的成员名单。
     */
    void onWhiteListRemoved(final String chatRoomId, final List<String> whitelist);
    
    /**
     * 全员禁言状态的变化。
     * @param chatRoomId    聊天室 ID。
     * @param isMuted       是否开启了全员禁言。
     */
    void onAllMemberMuteStateChanged(final String chatRoomId, final boolean isMuted);
    
    /**
     * 有成员设为管理员权限。
     * @param chatRoomId    聊天室 ID。
     * @param admin         设为管理员的成员。
     */
    void onAdminAdded(final String chatRoomId, final String admin);
    
    /**
     * 移除管理员权限。
     * @param  chatRoomId   聊天室 ID。
     * @param  admin        被移除的管理员。
     */
    void onAdminRemoved(final String chatRoomId, final String admin);
    
    /**
     * 转移聊天室所有者。
     * @param chatRoomId    聊天室 ID。
     * @param newOwner      新所有者。
     * @param oldOwner      原聊天室所有者。
     */
    void onOwnerChanged(final String chatRoomId, final String newOwner, final String oldOwner);

    /**
     * 聊天室公告更新事件。
     * @param chatRoomId    聊天室 ID。
     * @param announcement  更新的公告内容。
     */
    void onAnnouncementChanged(String chatRoomId, String announcement);
}
</code>