IM 即时通讯
Windows/macOS
开发指南

内置系统通知管理

更新时间: 2022/11/18 19:37:48

网易云信 NIM SDK 支持接收和存储内置系统通知。同时提供处理、查询、删除内置系统通知、修改通知状态等内置系统通知管理功能。

技术原理

内置系统通知是云信系统内建的通知,由云信服务器推送给用户或群组,用于云信系统类的事件通知。

系统通知相关 API 都挂载在 SDK 的 nim::SystemMsg 模块中,具体请参见 nim::SystemMsg

以上针对 C++ 接口接入,若需要以 C 接口接入,请参见nim_sysmsg。若需要以 C# 接口接入,请参见 NIM.SysMessage.SysMsgAPI

监听系统通知

只有在注册监听内置系统通知相关事件后,用户才会收到对应的系统通知。

uml diagram
C++

可以使用接收系统通知回调模板(ReceiveSysmsgCallback)并调用 RegSysmsgCb 方法来监听系统通知接收事件。

除了接收系统通知回调模板(ReceiveSysmsgCallback),SDK 还提供以下回调模板:

  • QueryMsgCallback:查询系统通知回调模板
  • NotifySysmsgResCallback:修改系统通知回调模板
  • QuerySysmsgUnreadCallback:查询系统通知未读数回调模板
  • ReadAllCallback:设置系统通知已读状态回调模板
  • DeleteAllCallback:删除全部系统通知回调模板
  • BatchSetCallback:批量调整系统通知回调模板
  • NotifySingleSysmsgCallback:修改(单条)系统通知回调模板
  • SetStatusCallback:设置系统通知状态回调模板
  • DeleteCallback:删除系统通知回调模板
  • SendCustomSysmsgCallback:发送自定义通知回调模板

示例代码:

void UIReceiveSysmsgCallback(nim::SysMessage& msg)
{
	if (msg.type_ == nim::kNIMSysMsgTypeCustomP2PMsg || msg.type_ == nim::kNIMSysMsgTypeCustomTeamMsg)
	{

	}
	else
	{

	}
}

void foo()
{
	nim::SystemMsg::RegSysmsgCb(&OnReceiveSysmsgCallback);
}
C

可以使用回调函数定义(nim_sysmsg_receive_cb_func)并调用 nim_sysmsg_reg_sysmsg_cb 方法来监听系统通知接收事件。

示例代码:

void CallbackSysmsgChange(const char *result, const char *json_extension, const void *callback)
{
	//解析result
}

typedef void(*nim_sysmsg_reg_sysmsg_cb)(const char *json_extension, nim_sysmsg_receive_cb_func cb, const void* user_data);

void foo()
{
	nim_sysmsg_reg_sysmsg_cb func = (nim_sysmsg_reg_sysmsg_cb) GetProcAddress(hInst, "nim_sysmsg_reg_sysmsg_cb");
	func("", &CallbackSysmsgChange, nullptr);
}
C#

通过调用 ReceiveSysMsgHandler 方法来监听系统通知接收事件。

示例代码:

void OnReceivedSysNotification(object sender, NIMSysMsgEventArgs e)
{
	if (e.Message == null || e.Message.Content == null)
		return;

	if (e.Message.Content.MsgType == NIMSysMsgType.kNIMSysMsgTypeTeamInvite)
	{
		
	}
}

void foo()
{
	NIM.SysMessage.SysMsgAPI.ReceiveSysMsgHandler += OnReceivedSysNotification;
}

注册后的回调通知给 APP。为了保证整个程序逻辑的一致性,APP 需要针对不同类型的系统通知进行相应的操作。

目前云信内置的能触发内置系统通知的事件包括:

通知类型 说明
kNIMSysMsgTypeTeamInvite 邀请用户加入高级群
kNIMSysMsgTypeTeamApply 用户申请加入高级群
kNIMSysMsgTypeTeamInviteReject 用户拒绝加入高级群邀请
kNIMSysMsgTypeTeamReject 拒绝用户的加入高级群申请
kNIMSysMsgTypeFriendAdd 加好友,通知内容 kNIMSysMsgKeyAttach: {"vt":verifyType} 中会返回具体的验证类型
kNIMSysMsgTypeFriendDel 删除好友
kNIMSysMsgTypeUnknown 未知类型,本地使用,发送时勿使用,作为默认

查询内置系统通知

C++

通过调用 QueryMsgAsync 方法查询本地所有的内置系统通知。

参数说明:

参数 说明
last_time 上次查询的最后一条系统通知的时间戳
limit_count 本次查询的系统通知数量,最多和默认都为 100 条
json_extension JSON 扩展参数
cb 结果回调函数,返回的列表按时间逆序逆序排列

示例代码:

void LoadEventsCb(int count, int unread, const std::list<nim::SysMessage> &result)
{

}

void foo()
{
	nim::SystemMsg::QueryMsgAsync(20, 0, &LoadEventsCb);
}

在支持数据库时,SDK 会将内置系统通知存储于数据库中。

:::

C

通过调用 nim_sysmsg_query_msg_async 方法查询本地所有的内置系统通知。

示例代码:

void CallbackSysmsgChange(int count, const char *result, const char *json_extension, const void *callback)
{
	//解析result
}

typedef void(*nim_sysmsg_query_msg_async)(int limit_count, __int64 last_time, const char *json_extension, nim_sysmsg_query_cb_func cb, const void* user_data);

void foo()
{
	nim_sysmsg_query_msg_async func = (nim_sysmsg_query_msg_async) GetProcAddress(hInst, "nim_sysmsg_query_msg_async");
	func(20, 0, "", &CallbackSysmsgChange, nullptr);
}
C#

通过调用 QueryMessage 方法查询本地所有的内置系统通知。

示例代码:

NIM.SysMessage.SysMsgAPI.QueryMessage(100, 0, (r) =>
{
});

删除内置系统通知

删除所有内置系统通知

C++

通过调用 DeleteAllAsync 方法删除所有的本地内置系统通知。示例代码如下:

void DeleteAllCb(nim::NIMResCode res_code, int unread)
{

}

void foo()
{
	nim::SystemMsg::DeleteAllAsync(&DeleteAllCb);
}
C

通过调用 nim_sysmsg_delete_all_async 方法删除所有的本地内置系统通知。示例代码如下:

void CallbackNotifySysmsgRes(int res_code, int unread_count, const char *json_extension, const void *callback)
{
	
}

typedef void(*nim_sysmsg_delete_all_async)(const char *json_extension, nim_sysmsg_res_cb_func cb, const void *user_data);

void foo()
{
	nim_sysmsg_delete_all_async func = (nim_sysmsg_delete_all_async) GetProcAddress(hInst, "nim_sysmsg_delete_all_async");
	func("", &CallbackNotifySysmsgRes, nullptr);
}
C#

通过调用 DeleteAll 方法删除所有的本地内置系统通知。示例代码如下:

void foo()
{
	NIM.SysMessage.SysMsgAPI.DeleteAll(
		(res_code, unread_count, json_extension, user_data) =>
	{

	});
}

删除指定的内置系统通知

C++

通过调用 DeleteAsync 方法根据 msg_id(系统通知 ID)删除指定的内置系统通知。示例代码如下:

void DeleteCb(nim::NIMResCode code, __int64 msg_id, int unread)
{

}

void foo(__int64 msg_id)
{
	nim::SystemMsg::DeleteAsync(msg_id, &DeleteCb);
}
C

通过调用 nim_sysmsg_delete_async 方法根据 msg_id(系统通知 ID)删除指定的内置系统通知。示例代码如下:

void CallbackNotifySingleSysmsg(int res_code, __int64 msg_id, int unread_count, const char *json_extension, const void *callback)
{
	
}

typedef void(*nim_sysmsg_delete_async)(__int64 msg_id, const char *json_extension, nim_sysmsg_res_ex_cb_func cb, const void *user_data);

void foo(__int64 msg_id)
{
	nim_sysmsg_delete_async func = (nim_sysmsg_delete_async) GetProcAddress(hInst, "nim_sysmsg_delete_async");
	func(msg_d, "", &CallbackNotifySingleSysmsg, nullptr);
}
C#

通过调用 DeleteByMsgId 方法根据 msgId(系统通知 ID)删除指定的内置系统通知。示例代码如下:

void foo(long msg_id)
{
	NIM.SysMessage.SysMsgAPI.DeleteByMsgId(msg_id,
		(res_code, _msg_id, unread_count, json_extension, user_data) =>
	{

	});
}

删除指定类型的内置系统通知

C++

通过调用 DeleteByTypeAsync 方法根据 type(系统通知类型)删除指定的内置系统通知。

系统通知类型具体请参见NIMSysMsgType

示例代码如下:

SystemMsg::DeleteByTypeAsync(kNIMSysMsgTypeTeamApply, [](NIMResCode res_code, int unread_count) {
	// process response
});
C

通过调用 nim_sysmsg_delete_logs_by_type_async 方法根据 type(系统通知类型)删除指定的内置系统通知。

系统通知类型具体请参见NIMSysMsgType

示例代码如下:

void DeleteByTypeCallback(int res_code, int unread_count, const char* json_extension, const void* callback){

}

nim_sysmsg_delete_logs_by_type_async(kNIMSysMsgTypeTeamApply, "", &DeleteByTypeCallback, NULL);
C#

通过调用 DeleteMsgByType 方法根据 type(系统通知类型)删除指定的内置系统通知。

系统通知类型具体请参见NIMSysMsgType

设置系统通知状态

SDK 的系统通知状态通过 NIMSysMsgStatus 来定义,目前主要内置了以下六种状态。

  • kNIMSysMsgStatusNone:未读,默认
  • kNIMSysMsgStatusRead :已读
  • kNIMSysMsgStatusPass :已通过
  • kNIMSysMsgStatusDecline :已拒绝
  • kNIMSysMsgStatusDeleted :已删除
  • kNIMSysMsgStatusInvalid :已失效

设置指定的内置系统通知状态

C++

通过调用 SetStatusAsync 方法根据 msg_id(系统通知 ID)设置指定的内置系统通知状态。示例代码如下:

void SetStatusCb(nim::NIMResCode code, __int64 msg_id, int unread)
{
	
}

void foo(__int64 msg_id)
{
	nim::SystemMsg::SetStatusAsync(msg_id_, nim::kNIMSysMsgStatusInvalid, &SetStatusCb);
}

更新的字段只会在本地数据库中更新,服务器上不会更新。

:::

C

通过调用 nim_sysmsg_set_status_async 方法根据 msg_id(系统通知 ID)设置指定的内置系统通知状态。示例代码如下:

void CallbackNotifySingleSysmsg(int res_code, __int64 msg_id, int unread_count, const char *json_extension, const void *callback)
{
	
}

typedef void(*nim_sysmsg_set_status_async)(__int64 msg_id, nim::NIMSysMsgStatus status, const char *json_extension, nim_sysmsg_res_ex_cb_func cb, const void* user_data);

void foo(__int64 msg_id, nim::NIMSysMsgStatus status)
{
	nim_sysmsg_set_status_async func = (nim_sysmsg_set_status_async) GetProcAddress(hInst, "nim_sysmsg_set_status_async");
	func(msg_d, status, "", &CallbackNotifySingleSysmsg, nullptr);
}
C#

通过调用 SetMsgStatus 方法根据 msgId(系统通知 ID)设置指定的内置系统通知状态。示例代码如下:

void foo(long msg_id)
{
	NIM.SysMessage.SysMsgAPI.SetMsgStatus(msg_id, NIM.SysMessage.NIMSysMsgStatus.kNIMSysMsgStatusRead, 
		(res_code, _msg_id, unread_count, json_extension, user_data) =>
	{

	});
}

设置指定类型的内置系统通知状态

C++

通过调用 SetStatusByTypeAsync 方法根据 type(系统通知类型)设置指定类型的内置系统通知状态。示例代码如下:

SystemMsg::SetStatusByTypeAsync(kNIMSysMsgTypeTeamApply, kNIMSysMsgStatusPass, [](NIMResCode res_code, int unread_count) {
	// process response
	// ...
});

  • 系统通知类型具体请参见NIMSysMsgType
  • 更新的字段只会在本地数据库中更新,服务器上不会更新。

:::

C

通过调用 nim_sysmsg_set_logs_status_by_type_async 方法根据 type(系统通知类型)设置指定类型的内置系统通知状态。示例代码如下:

static void CallbackNotifySysmsgRes(int res_code, int unread_count, const char* json_extension, const void* callback) {
    // process response
	// ...
}
nim_sysmsg_set_logs_status_by_type_async)(type, kNIMSysMsgStatusPass, "", &CallbackNotifySysmsgRes, NULL);
C#

通过调用 SetMsgStatusByType 方法根据 type(系统通知类型)设置指定类型的内置系统通知状态。

API 参考

C++
API
说明
RegSysmsgCb 监听系统通知接收事件
QueryMsgAsync 查询所有的本地内置系统通知
DeleteAllAsync 删除所有的本地内置系统通知
DeleteAsync 根据 msg_id(系统通知 ID)删除指定的内置系统通知
DeleteByTypeAsync 根据 type(系统通知类型)删除指定的内置系统通知
SetStatusAsync 根据 msg_id(系统通知 ID)设置指定的内置系统通知状态
SetStatusByTypeAsync 根据 type(系统通知类型)设置指定类型的内置系统通知状态
C
API
说明
nim_sysmsg_reg_sysmsg_cb 监听系统通知接收事件
nim_sysmsg_query_msg_async 查询所有的本地内置系统通知
nim_sysmsg_delete_all_async 删除所有的本地内置系统通知
nim_sysmsg_delete_async 根据 msg_id(系统通知 ID)删除指定的内置系统通知
nim_sysmsg_delete_logs_by_type_async 根据 type(系统通知类型)删除指定的内置系统通知
nim_sysmsg_set_status_async 根据 msg_id(系统通知 ID)设置指定的内置系统通知状态
nim_sysmsg_set_logs_status_by_type_async 根据 type(系统通知类型)设置指定类型的内置系统通知状态
C#
API
说明
ReceiveSysMsgHandler 监听系统通知接收事件
QueryMessage 查询所有的本地内置系统通知
DeleteAll 删除所有的本地内置系统通知
DeleteByMsgId 根据 msgId(系统通知 ID)删除指定的内置系统通知
DeleteMsgByType 根据 type(系统通知类型)删除指定的内置系统通知
SetMsgStatus 根据 msgId(系统通知 ID)设置指定的内置系统通知状态
SetMsgStatusByType 根据 type(系统通知类型)设置指定类型的内置系统通知状态
此文档是否对你有帮助?
有帮助
去反馈
  • 技术原理
  • 监听系统通知
  • 查询内置系统通知
  • 删除内置系统通知
  • 删除所有内置系统通知
  • 删除指定的内置系统通知
  • 删除指定类型的内置系统通知
  • 设置系统通知状态
  • 设置指定的内置系统通知状态
  • 设置指定类型的内置系统通知状态
  • API 参考