IM 即时通讯
Windows/macOS
动态与公告
Demo 更新日志
NIM SDK 更新日志
产品介绍
简介
主要功能
产品优势
海外数据中心
IM平滑迁移方案
接口及业务限制
功能介绍
账号集成与登录
多端登录与互踢策略
基础消息功能
群组功能
聊天室功能
聊天室标签功能
圈组功能
质量数据监控台
快速开始
实现单聊消息收发(不含 UI)
实现圈组消息收发(不含 UI)
开发指南
概要介绍
集成方式(当前版本)
集成方式(Windows旧版本)
集成方式(macOS旧版本)
初始化
登录相关
登录 IM
多端登录与互踢
登出 IM
消息收发
最近会话
历史记录
用户资料托管
好友关系托管
事件订阅
系统通知
系统通知概述
内置系统通知管理
内置系统通知未读数
自定义系统通知收发
群组功能
群组概述
群组管理
群成员管理
群消息管理
超大群功能
开通聊天室功能
聊天室
圈组功能
初始化
登录圈组
圈组服务器管理
圈组服务器成员管理
游客功能
频道相关
频道管理
频道分组
频道分组黑白名单
频道未读数管理
搜索服务器和频道
身份组相关
身份组概述
身份组应用场景
服务器身份组
频道身份组
频道分组身份组
频道用户定制权限
自定义权限项
成员权限判定
身份组相关查询
圈组订阅机制
圈组消息相关
圈组消息收发
圈组消息撤回
圈组消息更新
圈组消息删除
会话消息回复(Thread)
圈组快捷评论
获取频道最后一条消息
消息正在输入
圈组消息搜索
圈组消息查询
查询@我的消息
服务器未读数
圈组系统通知
圈组系统通知概述
圈组系统通知收发
圈组系统通知更新
圈组各端接口命名差异
语音录制与播放
NOS云存储服务
文档转换
反垃圾(内容审核)
接入第三方机器人
API 参考
Windows/macOS API 参考
状态码/错误码
IM 控制台指南
创建应用
注册 IM 账号
升级服务
配置应用客户端标识
参考文档
升级指引
开发示例
UI库指南
Demo源码导读
打包发布
类与常量定义说明
常见问题
FAQ
服务协议

频道分组

更新时间: 2023/05/24 10:39:54

本文介绍频道分组的技术原理、创建频道分组的实现方法以及相关示例代码。

技术原理

网易云信即时通讯 NIM Windows SDK 的NIMQChatChannelCategoryInfo结构体定义了频道分组。同时,SDK 的ChannelCategory类提供管理频道分组的相关方法,助您快速实现对频道的分类管理。

频道管理相关方法,基本都需要满足如下两个前提条件才能调用。各方法的具体调用前提,请参见本文的 API参考

  • 频道分组对用户可见,具体机制见下文的频道分组可见机制
  • 拥有管理频道的权限(NIMQChatPermission枚举中的kPermissionManageChannel)。

频道分组可见机制

  • 频道分组对服务器成员的可见机制与频道的类似,分如下两种情况:

    • 如果频道分组为公开频道分组,那么只要用户未被加入频道分组黑名单,频道分组就对其可见。
    • 如果频道分组为私密频道分组,那么用户需被加入频道分组白名单,频道分组才对其可见。

    频道分组黑白名单相关说明,请参见频道分组黑白名单

  • 频道分组是否对游客可见,取决于频道分组内是否有频道对游客可见。如果频道分组内有频道对游客可见,则该频道分组对游客也可见。频道是否对游客可见由visitor_mode决定,可在创建频道和修改频道时设置,具体见频道管理

    如果频道的 visitor_mode 为跟随模式,且同步模式(sync_mode)为“与频道分组同步”,则当该频道所属的频道分组的查看模式(view_mode)变更后,该频道对游客的可见性也将变更。例如,在这种情况下,频道分组的查看模式由公开变为私密,则此时该频道对游客从“可见”变为“不可见”。

频道分组与频道的关联逻辑

频道管理相关方法(如CreateChannel)的入参包含category_idsync_mode。在调用CreateChannel时传入category_id可将频道加入某个频道分组;通过设置sync_mode,可实现频道数据与频道分组数据的同步。具体同步的数据包括查看模式(私密或公开)、黑白名单和身份组权限。

参数
类型
说明
category_id long 频道需加入或所在的频道分组 ID。设置为 0 表示频道没有频道分组。设置为频道分组 ID 表示归属某个频道分组
sync_mode NIMQChatChannelSyncMode
频道同步模式
  • kNIMQChatChannelSyncModeSync同步
  • kNIMQChatChannelSyncModeNoSync不同步
  • 不传默认不同步
  • 如果频道查看模式、黑白名单、身份组权限等被修改,自动改为不同步

归属于单个频道分组的频道数量上限为 50。

频道分组与服务器的关联逻辑

定义了服务器的NIMQChatServerInfo结构体中包含channel_category_count参数,该参数表示服务器内频道分组的数量。

服务器内频道分组数量上限为 100。

频道分组与系统通知的关联逻辑

频道分组相关事件的系统通知为 SDK 内置系统通知,在NIMQChatSystemNotificationType枚举内定义。具体类型及相关的触发和接收条件见下表。

系统通知类型
触发条件
接收条件
kNIMQChatSystemNotificationTypeChannelCategoryCreate 频道分组成功创建时
  • 服务器创建者和所有者:在线
  • 其他成员:服务器成员数量低于 2,000 人阈值时只需要在线。如大于 2,000,需在线且订阅服务器
kNIMQChatSystemNotificationTypeChannelCategoryRemove 频道分组被删除时
  • 删除者和服务器所有者:在线
  • 其他成员:服务器成员数量低于 2,000 人阈值时只需要在线。如大于 2,000,需在线且订阅服务器
kNIMQChatSystemNotificationTypeChannelCategoryUpdate 频道分组信息被修改时
  • 修改者和服务器所有者:在线
  • 其他成员:服务器成员数量低于 2,000 人阈值时只需要在线。如大于 2,000,需在线且订阅服务器
kNIMQChatSystemNotificationTypeChannelCategoryWhiteBlackRoleUpdate 频道分组黑白名单身份组被修改时
  • 修改者、服务器所有者和身份组成员(身份组成员限制 100 人):在线
  • 其他成员:服务器成员数量低于 2,000 人阈值时只需要在线。如大于 2,000,需在线且订阅服务器
kNIMQChatSystemNotificationTypeChannelCategoryWhiteBlackMembersUpdate 频道分组黑白名单成员被修改时
  • 修改者、服务器所有者和被加入/移出黑白名单的用户:在线
  • 其他成员:服务器成员数量低于 2,000 人阈值时只需要在线。如大于 2,000,需在线且订阅服务器

2,000 人阈值可联系商务经理调整。

实现方法

本节以服务器所有者(即创建者)和服务器成员的交互为例,介绍服务器成员创建频道分组的实现流程。

  • 服务器所有者拥有全局权限,可以在创建服务器后直接调用CreateChannelCategory方法创建频道分组。
  • 用户创建频道分组后, 可对频道分组做更新、删除、修改和查询等操作,相关可调用的方法请参见本文的API参考

前提条件

  • 接入圈组,并已创建圈组服务器和身份组。
  • 创建 2 个云信 IM 账号,作为下文中服务器所有者和服务器成员的云信 IM 账号。

实现流程

  1. 服务器所有者调用AddMembersToServerRole方法,将服务器成员加入身份组。
  2. 服务器所有者调用UpdateServerRole方法,授予该身份组管理频道的权限(NIMQChatPermissionType)。
  3. 服务器成员调用CreateChannelCategory方法创建频道分组。

API 调用时序图

uml diagram

示例代码


// A: add user B to server role
QChatAddMembersToServerRoleParam param;
param.server_id = 123456;
param.role_id = 123456;
param.members_accids = {"B"};
param.cb = [this](const QChatAddMembersToServerRoleResp& resp) {
    if (resp.res_code != NIMResCode::kNIMResSuccess) {
        // error handling
        return;
    }
    // process response
    // ...
};
Role::AddMembersToServerRole(param);

// A: update server role to enable create channel category permission
QChatUpdateServerRoleParam param;
param.info.server_id = 123456;
param.info.role_id = 123456;
param.info.permissions[kPermissionManageChannel] = kPermissionSwitchAllow;
param.cb = [this](const QChatUpdateServerRoleResp& resp) {
    if (resp.res_code != NIMResCode::kNIMResSuccess) {
        // error handling
        return;
    }
    // process response
    // ...
};
Role::UpdateServerRole(param);



// B: now B has permission to create channel category
QChatChannelCategoryCreateParam param;
param.server_id = 123456;
param.name = "channel category name";
param.custom = "channel category custom";
param.view_mode = kNIMQChatChannelViewModePublic;
param.cb = [this](const QChatChannelCategoryCreateResp& resp) {
    if (resp.res_code != NIMResCode::kNIMResSuccess) {
        // error handling
        return;
    }
    // process response
    // ...
};
ChannelCategory::CreateChannelCategory(param);

API参考

API
调用前提
说明
CreateChannelCategory 用户拥有管理频道的权限 创建频道分组
RemoveChannelCategory 频道分组对用户可见,且用户拥有管理频道的权限 删除频道分组
UpdateChannelCategory 频道分组对用户可见,且用户拥有管理频道的权限 修改频道分组信息
GetChannelCategoriesByID 按分组 ID 查询频道分组
GetChannelCategoryChannelsPage 频道分组对用户可见,且用户拥有管理频道的权限 分页查询频道分组下频道列表
GetChannelCategoriesPage 频道分组对用户可见,且用户拥有管理频道的权限 分页查询频道分组列表
此文档是否对你有帮助?
有帮助
我要吐槽
  • 技术原理
  • 频道分组可见机制
  • 频道分组与频道的关联逻辑
  • 频道分组与服务器的关联逻辑
  • 频道分组与系统通知的关联逻辑
  • 实现方法
  • 前提条件
  • 实现流程
  • API 调用时序图
  • 示例代码
  • API参考