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.
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 notificationsNotifySysmsgResCallback
: Modify the system notificationQuerySysmsgUnreadCallback
: 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 notificationSetStatusCallback
: Set the status of a system notificationDeleteCallback
: Delete a system notificationSendCustomSysmsgCallback
: 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);
}
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
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.
:::
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
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);
}
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
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);
}
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
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
});
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 defaultkNIMSysMsgStatusRead
: ReadkNIMSysMsgStatusPass
: PassedkNIMSysMsgStatusDecline
: RejectedkNIMSysMsgStatusDeleted
: DeletedkNIMSysMsgStatusInvalid
: Invalid
Set the status of the specified built-in system notifications
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.
:::
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
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.
:::
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
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. |
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. |