频道黑白名单用于管控频道对服务器成员是否可见。圈组支持选择服务器成员加入黑名单或白名单，或者选择身份组将身份组所有成员批量加入黑名单或白名单。

被加入黑白名单的用户，即为黑白名单成员；被加入黑名单或白名单的身份组即为黑白名单身份组。

功能介绍

频道的可见性管控是圈组消息流转中的一个环节，管控方式根据频道的查看模式存在区分，具体如下：

频道查看模式	可见性管控
公开	通过频道黑名单进行管控，频道对黑名单中的服务器成员不可见，即这些成员无法访问该频道，其他服务器成员均可访问该频道
私密	通过频道白名单进行管控，频道对白名单中的服务器成员可见，即这些成员可访问该频道，其他服务器成员均无法访问该频道

前提条件

• 已注册observeReceiveSystemNotification监听圈组的系统通知。示例代码参见圈组系统通知收发。

  具体与频道黑白名单相关的系统通知类型，见本文末尾的相关系统通知。

• 已创建频道。

实现方法

管理黑白名单成员

更新频道黑白名单成员

用户可调用updateChannelBlackWhiteMembers方法更新频道的黑白名单，将服务器成员加入或移出黑白名单，从而管控服务器成员是否可访问频道。

• 调用该方法需拥有管理黑白名单的权限（QChatRoleResource.MANAGE_BLACK_WHITE_LIST）。

• 单个频道的黑白名单成员人数上限，默认为 1000。

  可在云信控制台配置该数量上限，配置路径：在云信控制台选择应用，进入IM 免费版/专业版 > 功能权限开通 > 拓展配置 > 圈组 > 高级配置 > 公开私密频道的黑白名单成员数。

QChatUpdateChannelBlackWhiteMembersParam为其入参结构，具体参数说明如下：

返回值	参数	说明
Long	getServerId()	获取服务器 ID
Long	getChannelId()	获取频道 ID
QChatChannelBlackWhiteType	getType()	获取黑白名单类型 QChatChannelBlackWhiteType.WHITE：白名单 QChatChannelBlackWhiteType.BLACK：黑名单
QChatChannelBlackWhiteOperateType	getOperateType()	获取黑白名单操作类型: QChatChannelBlackWhiteOperateType.ADD:添加 QChatChannelBlackWhiteOperateType.REMOVE:移除
List< String>	getToAccids()	获取账户accid列表：添加或者移除到黑白名单的accid列表

示例代码如下：

//将accids中的这些账户添加到黑名单中
NIMClient.getService(QChatChannelService.class).updateChannelBlackWhiteMembers(new QChatUpdateChannelBlackWhiteMembersParam(943445L,885305L,
        QChatChannelBlackWhiteType.BLACK, QChatChannelBlackWhiteOperateType.ADD,accids)).setCallback(new RequestCallback<Void>() {
    @Override
    public void onSuccess(Void result) {
        //更新Channel黑白名单成员成功

    }

    @Override
    public void onFailed(int code) {
        //更新Channel黑白名单成员失败，返回错误code
    }

    @Override
    public void onException(Throwable exception) {
        //更新Channel黑白名单成员异常
    }
});

分页查询频道黑白名单成员

调用getChannelBlackWhiteMembersByPage方法，可分页查询频道黑白名单。调用时需要传入查询的 serverId、channelId、黑白名单类型、查询锚点时间戳timeTag 和查询数量限制limit。

调用该方法需要拥有管理频道黑白名单的权限（QChatRoleResource.MANAGE_BLACK_WHITE_LIST）。

示例代码如下：

//查处频道黑名单中的成员列表
NIMClient.getService(QChatChannelService.class).getChannelBlackWhiteMembersByPage(new QChatGetChannelBlackWhiteMembersByPageParam(943445L,885305L,QChatChannelBlackWhiteType.BLACK,System.currentTimeMillis())).setCallback(new RequestCallback<QChatGetChannelBlackWhiteMembersByPageResult>() {
    @Override
    public void onSuccess(QChatGetChannelBlackWhiteMembersByPageResult result) {
        //查询成功,返回频道黑名单中成员列表
        List<QChatServerMember> members = result.getMemberList();
        //下一页的起始时间戳
        long nextTimeTag = result.getNextTimeTag();
        //是否还有下一页
        boolean hasMore = result.isHasMore();
    }

    @Override
    public void onFailed(int code) {
        //查询失败，返回错误code
    }

    @Override
    public void onException(Throwable exception) {
        //查询异常
    }
});

批量查询频道黑白名单成员

调用getExistingChannelBlackWhiteMembers方法可根据传入的用户账号（accid）列表查询其中已被加入的黑白名单的用户。

单次调用最多可传入 100 个 accid。

示例代码如下：

//查询频道中存在的黑名单成员
List<String> accidList = getQueryAccids();
QChatGetExistingChannelBlackWhiteMembersParam param = new QChatGetExistingChannelBlackWhiteMembersParam(currentChannel.getServerId(),currentChannel.getChannelId(), QChatChannelBlackWhiteType.BLACK,accidList);
NIMClient.getService(QChatChannelService.class).getExistingChannelBlackWhiteMembers(param).setCallback(
        new RequestCallback<QChatGetExistingChannelBlackWhiteMembersResult>() {
            @Override
            public void onSuccess(QChatGetExistingChannelBlackWhiteMembersResult result) {
                //查询到的在黑名单中的成员
                List<QChatServerMember> memberList = result.getMemberList();
            }

            @Override
            public void onFailed(int code) {
                //查询失败，返回错误code
            }

            @Override
            public void onException(Throwable exception) {
                //查询异常
            }
        });

管理黑白名单身份组

更新频道黑白名单身份组

调用updateChannelBlackWhiteRoles方法可选择身份组将所选身份组的成员批量加入或移出频道黑白名单，加入黑白名单的身份组即为黑白名单身份组。调用时需要传入服务器 ID（serverId）、频道 ID（channelId）、黑白名单类型、黑白名单操作类型和身份组 ID 列表。、

• 调用该方法需要拥有管理频道黑白名单的权限（QChatRoleResource.MANAGE_BLACK_WHITE_LIST）。

• 单个频道可设置的黑白名单身份组的数量上限，默认为 20。

  可在云信控制台配置该数量上限

  在云信控制台选择应用，进入IM 免费版/专业版 > 功能权限开通 > 拓展配置 > 圈组 > 高级配置 > channel公开私密频道的黑白名单身份组对象数即可配置。
  

示例代码如下：

NIMClient.getService(QChatChannelService.class).updateChannelBlackWhiteRoles(new QChatUpdateChannelBlackWhiteRolesParam(943445L,885305L,
        QChatChannelBlackWhiteType.BLACK, QChatChannelBlackWhiteOperateType.ADD,roleIds)).setCallback(new RequestCallback<Void>() {
    @Override
    public void onSuccess(Void result) {
        //更新Channel黑白名单身份组成功

    }

    @Override
    public void onFailed(int code) {
        //更新Channel黑白名单身份组失败，返回错误code
    }

    @Override
    public void onException(Throwable exception) {
        //更新Channel黑白名单身份组异常
    }
});

分页查询黑白名单身份组列表

调用getChannelBlackWhiteRolesByPage方法可分页查询频道的黑白名单身份组列表。 调用时需要传入服务器 ID、频道 ID、黑白名单类型、查询锚点时间戳 timeTag 和查询数量限制 limit。

调用该方法需要拥有管理频道黑白名单的权限（QChatRoleResource.MANAGE_BLACK_WHITE_LIST）。

示例代码如下：

//查处频道黑名单中的身份组列表
NIMClient.getService(QChatChannelService.class).getChannelBlackWhiteRolesByPage(new QChatGetChannelBlackWhiteRolesByPageParam(943445L,885305L,QChatChannelBlackWhiteType.BLACK,System.currentTimeMillis())).setCallback(new RequestCallback<QChatGetChannelBlackWhiteRolesByPageResult>() {
    @Override
    public void onSuccess(QChatGetChannelBlackWhiteRolesByPageResult result) {
        //查询成功,返回频道黑名单中身份组列表
        List<QChatServerRole> roleList = result.getRoleList();
        //下一页的起始时间戳
        long nextTimeTag = result.getNextTimeTag();
        //是否还有下一页
        boolean hasMore = result.isHasMore();
    }

    @Override
    public void onFailed(int code) {
        //查询失败，返回错误code
    }

    @Override
    public void onException(Throwable exception) {
        //查询异常
    }
});

批量查询黑白名单身份组列表

调用getExistingChannelBlackWhiteRoles方法可根据传入的身份组 ID 列表批量查询其中被加入黑白名单的身份组。

单次调用最多可传入 100 个身份组的 ID。

示例代码如下：

//查询频道中存在的黑名单身份组
List<Long> roleIds = getQueryRoles();
        QChatGetExistingChannelBlackWhiteRolesParam param = new QChatGetExistingChannelBlackWhiteRolesParam(currentChannel.getServerId(),
                currentChannel.getChannelId(), QChatChannelBlackWhiteType.BLACK,roleIds);
        NIMClient.getService(QChatChannelService.class).getExistingChannelBlackWhiteRoles(param).setCallback(
                new RequestCallback<QChatGetExistingChannelBlackWhiteRolesResult>() {
                    @Override
                    public void onSuccess(QChatGetExistingChannelBlackWhiteRolesResult result) {
                        //查询到的在黑名单中的身份组列表
                        List<QChatServerRole> roleList = result.getRoleList();
                    }

                    @Override
                    public void onFailed(int code) {
                        //查询失败，返回错误code
                    }

                    @Override
                    public void onException(Throwable exception) {
                        //查询异常
                    }
                });

相关系统通知

圈组系统通知的类型在QChatSystemNotificationType枚举中定义，与频道黑白名单相关的内置系统通知类型如下：

枚举值	说明
CHANNEL_UPDATE_WHITE_BLACK_MEMBER	更新“频道黑白名单成员”
CHANNEL_UPDATE_WHITE_BLACK_ROLE	更新“频道黑白名单身份组”

这两种系统通知的接收条件，请参见服务端文档的频道相关事件通知。