Manage Built-in System Notifications

Update time: 2023/03/23 09:19:21

NIM SDK receives and stores built-in system notifications. You are allowed to handle, query, delete built-in system notifications and set status of built-in system notifications.

How it works

Built-in system notifications delivered by the CommsEase server to users or groups used for system events.

The APIs to manipulate system notifications are defined in nim::SystemMsg. For more information, see nim::SystemMsg.

The previous module are implemented in C++. For the implementation in C language, see nim_sysmsg. For the implementation in C# language, see NIM.SysMessage.SysMsgAPI.

Listener for system notifications

Only after registering the listener for events of built-in system notification, users will receive the corresponding system notifications.

System_notifications.png

C++

Use the callback template (ReceiveSysmsgCallback) and call the RegSysmsgCb method to listen to the system events.

In addition to the callback template (ReceiveSysmsgCallback), the SDK also provides the following callback templates:

  • QueryMsgCallback: Query system notifications
  • NotifySysmsgResCallback: Modify the system notification
  • QuerySysmsgUnreadCallback: Query the number of unread system notifications.
  • ReadAllCallback: Mark all system notifications read.
  • DeleteAllCallback: Delete all system notifications.
  • BatchSetCallback: Set multiple system notifications.
  • NotifySingleSysmsgCallback: Edit one system notification
  • SetStatusCallback: Set the status of a system notification
  • DeleteCallback: Delete a system notification
  • SendCustomSysmsgCallback: Send custom notifications

Sample code:

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

	}
	else
	{

	}
}

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

Use the callback function definition (nim_sysmsg_receive_cb_func) and call the nim_sysmsg_reg_sysmsg_cb method to listen to the system events.

Sample code:

cppvoid CallbackSysmsgChange(const char *result, const char *json_extension, const void *callback)
{
	//Parse the 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);
}

The registered callback sends a notification to the APP. To ensure the consistency of the entire program logic, the APP must perform corresponding operations for different types of system notifications.

The built-in system notifications are available for the following events:

Type Description
kNIMSysMsgTypeTeamInvite Invite a user to join an advanced group
kNIMSysMsgTypeTeamApply Request to join an advanced group
kNIMSysMsgTypeTeamInviteReject Reject to join an advanced group.
kNIMSysMsgTypeTeamReject Reject a request to join request
kNIMSysMsgTypeFriendAdd Add a friend. The kNIMSysMsgKeyAttach: {"vt":verifyType} returns the specific verification type.
kNIMSysMsgTypeFriendDel Delete a friend
kNIMSysMsgTypeUnknown Unknown type, used for local behaviors, irgored by default.

Query built-in system notifications

C++

Query built-in system notifications in the local database by calling the QueryMsgAsync method

Parameters:

Parameter Description
last_time The timestamp of the message queried last time.
limit_count The number of system notifications returned in this query, the maximum and default value are 100.
json_extension Extension in JSON.
Cb callback for the result, the returned list is sorted in descending order by time.

Sample code:

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

}

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

The SDK stores built-in system notifications in the database.

:::

C

Query built-in system notifications in the local database by calling the nim_sysmsg_query_msg_async method.

Sample code:

cppvoid CallbackSysmsgChange(int count, const char *result, const char *json_extension, const void *callback)
{
	//Parse the 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);
}

Delete built-in system notifications

Delete all built-in system notifications

C++

Delete all built-in system notifications by calling the DeleteAllAsync method. Sample code:

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

}

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

Delete all built-in system notifications nim_sysmsg_delete_all_async method. Sample code:

cppvoid 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);
}

Delete specified built-in system notifications

C++

Delete specified built-in system notifications by notification ID by calling the DeleteAsync method. Sample code:

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

}

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

Delete specified built-in system notifications by notification ID by calling the nim_sysmsg_delete_async method. Sample code:

cvoid 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);
}

Delete built-in system notifications of specified type

C++

Delete built-in system notifications of specified type by calling the DeleteByTypeAsync method.

For information about types of system notifications, see NIMSysMsgType .

Sample code:

cppSystemMsg::DeleteByTypeAsync(kNIMSysMsgTypeTeamApply, [](NIMResCode res_code, int unread_count) {
	// Handle responses
});
C

Delete built-in system notifications of specified type by calling the nim_sysmsg_delete_logs_by_type_async method.

For information about types of system notifications, see NIMSysMsgType.

Sample code:

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

}

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

Set the status of system notifications

The status of system notifications are defined in NIMSysMsgStatus . The following states are supported.

  • kNIMSysMsgStatusNone: Unread, by default
  • kNIMSysMsgStatusRead : Read
  • kNIMSysMsgStatusPass : Passed
  • kNIMSysMsgStatusDecline : Rejected
  • kNIMSysMsgStatusDeleted : Deleted
  • kNIMSysMsgStatusInvalid : Invalid

Set the status of the specified built-in system notifications

C++

Set the status of the specified built-in system notifications by notification ID by calling the SetStatusAsync method. Sample code:

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

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

Fields will only be updated in the local database, not on the server.

:::

C

Set the status of the specified built-in system notifications by calling the nim_sysmsg_set_status_async method. Sample code:

cvoid 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);
}

Set the status of built-in system notifications of specified type

C++

Set the status of built-in system notifications of specified type by calling the SetStatusByTypeAsync method. Sample code:

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

  • For information about types of system notifications, see NIMSysMsgType.
  • Fields will only be updated in the local database, not on the server.

:::

C

Set the status of built-in system notifications of specified type by calling the nim_sysmsg_set_logs_status_by_type_async method. Sample code:

cstatic 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);

API reference

C++
API
Description
RegSysmsgCb Listen to the event of receiving system notifications.
QueryMsgAsync Query all local built-in system notifications.
DeleteAllAsync Delete all local built-in system notifications.
DeleteAsync Delete specified built-in system notifications by notification ID.
DeleteByTypeAsync Delete built-in system notifications of specified type.
SetStatusAsync Set the status of a specified built-in system notification by notification ID.
SetStatusByTypeAsync Set the status of system notifications of specified type.
C
API
Description
nim_sysmsg_reg_sysmsg_cb Listen to the event of receiving system notifications.
nim_sysmsg_query_msg_async Query all local built-in system notifications.
nim_sysmsg_delete_all_async Delete all local built-in system notifications.
nim_sysmsg_delete_async Delete specified built-in system notifications by notification ID.
nim_sysmsg_delete_logs_by_type_async Delete built-in system notifications of specified type.
nim_sysmsg_set_status_async Set the status of a specified built-in system notification by notification ID.
nim_sysmsg_set_logs_status_by_type_async Set the status of system notifications of specified type.
Was this page helpful?
Yes
No
  • How it works
  • Listener for system notifications
  • Query built-in system notifications
  • Delete built-in system notifications
  • Delete all built-in system notifications
  • Delete specified built-in system notifications
  • Delete built-in system notifications of specified type
  • Set the status of system notifications
  • Set the status of the specified built-in system notifications
  • Set the status of built-in system notifications of specified type
  • API reference