事件订阅

事件订阅,允许用户订阅其他人发布的事件,当被订阅人发布事件后,订阅者可以收到事件通知。事件分为系统预定义事件和自定义事件,系统预定义事件类型范围为1-99999,用户自定义事件范围必须大于99999。 对于用户自定义事件,用户可以根据自己的需求场景来指定不同的事件类型和事件来定义不同的含义;对于系统预定义事件,系统保留1~9999的事件值,用户如果要发送系统预定义事件,事件值必须大于9999。

目前系统预定义事件只有在线状态事件,事件类型为1,事件值为:1 - 用户登录,2 - 用户登出,3 - 用户与服务器连接断开。当用户登录、登出、异常退出后,服务器会下发响应的在线状态事件值来通知订阅者。用户在某端订阅或者取消订阅某些事件,会同时对其他端的生效,所以取消订阅事件时需谨慎,防止影响了其他端。

接收事件

提前注册好接收事件的回调函数,在登录后,回调函数会收到订阅的事件信息。需要注册两个回调函数:接收订阅事件回调函数、批量接收订阅的事件的回调函数。

/** @fn void nim_subscribe_event_reg_push_event_cb(const char *json_extension, nim_push_event_cb_func cb, const void *user_data)
  * (全局回调)统一注册接收订阅的事件的回调函数
  * @param[in] json_extension    json扩展参数(备用,目前不需要)
  * @param[in] cb                接收订阅事件的回调函数, nim_push_event_cb_func回调函数定义见nim_subscribe_event_def.h
  * @param[in] user_data        APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理!
  * @return void 无返回值
  * @note 错误码    200:成功
  */
NIM_SDK_DLL_API void nim_subscribe_event_reg_push_event_cb(const char *json_extension, nim_push_event_cb_func cb, const void *user_data);

/** @fn void nim_subscribe_event_reg_batch_push_event_cb(const char *json_extension, nim_batch_push_event_cb_func cb, const void *user_data)
  * (全局回调)统一注册批量接收订阅的事件的回调函数
  * @param[in] json_extension    json扩展参数(备用,目前不需要)
  * @param[in] cb                批量接收订阅事件的回调函数, nim_batch_push_event_cb_func回调函数定义见nim_subscribe_event_def.h
  * @param[in] user_data        APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理!
  * @return void 无返回值
  * @note 错误码    200:成功
  */
NIM_SDK_DLL_API void nim_subscribe_event_reg_batch_push_event_cb(const char *json_extension, nim_batch_push_event_cb_func cb, const void *user_data);

发布事件

用户可以根据自己的需求来发布系统预定义事件或自定义事件。发布事件时,需要指定事件类型、事件值、事件消息id、事件有效期、事件广播类型、事件同步类型,可以根据需求选择是否附加自定义事件扩展属性。其中事件有效期范围为:60s到7天,单位秒,订阅者在有效期内登录才可以收到对应的事件;事件广播类型指定是否通知离线订阅者;事件同步类型指定是否把事件同步给自己的其他端;自定义事件扩展属性可以设置任意字符串。

/** @fn void nim_publish_event(const char *event_json, const char *json_extension, nim_publish_event_cb_func cb, const void *user_data)
  * 发布事件
  * @param[in] event_json        事件json字符串
  * @param[in] json_extension    json扩展参数(备用,目前不需要)
  * @param[in] cb                操作结果回调, nim_publish_event_cb_func回调函数定义见nim_subscribe_event_def.h
  * @param[in] user_data        APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理!
  * @return void 无返回值
  * @note 错误码    200:成功
  *                403:应用没开通事件服务
  *                404:禁用了特定事件
  *                414:参数错误
  *                500:未知错误
  */
NIM_SDK_DLL_API void nim_publish_event(const char *event_json, const char *json_extension, nim_publish_event_cb_func cb, const void *user_data);

订阅事件

只有先订阅了某个用户的某个事件后,才可以收到对应用户发布的事件。订阅事件,需要指定事件类型、订阅有效期、订阅后是否立即同步最新事件。其中订阅有效期范围为:60s到30天,单位秒,如果订阅有效期超时后,需要重新订阅才可以继续收到事件

/** @fn void nim_subscribe_event(int event_type, int64_t ttl, int sync_event, const char *accid_list_json, const char *json_extension, nim_subscribe_event_cb_func cb, const void *user_data)
  * 订阅事件
  * @param[in] event_type        事件类型
  * @param[in] ttl                订阅有效期,单位:秒,范围:60s到30天
  * @param[in] sync_event        订阅后是否立即同步最新事件,见nim_subscribe_event_def.h中NIMEventSubscribeSyncType定义
  * @param[in] accid_list_json    用户列表,例 ["litianyi01", "litianyi02", ...]
  * @param[in] json_extension j    son扩展参数(备用,目前不需要)
  * @param[in] cb                操作结果回调, nim_subscribe_event_cb_func回调函数定义见nim_subscribe_event_def.h
  * @param[in] user_data        APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理!
  * @return void 无返回值
  * @note 错误码    200:成功
  *                414:参数错误
  *                500:未知错误
  */
NIM_SDK_DLL_API void nim_subscribe_event(int event_type, int64_t ttl, int sync_event, const char *accid_list_json, const char *json_extension, nim_subscribe_event_cb_func cb, const void *user_data);

取消订阅事件

不想接收事件时可以取消订阅该事件,取消后不会收到事件的通知。可以取消指定好友发布的事件,也可以取消所有订阅的事件。

/** @fn void nim_unsubscribe_event(int event_type, const char *accid_list_json, const char *json_extension, nim_unsubscribe_event_cb_func cb, const void *user_data)
  * 按账号取消指定事件的订阅关系
  * @param[in] event_type        事件类型
  * @param[in] accid_list_json    用户列表,例 ["litianyi01", "litianyi02", ...]
  * @param[in] json_extension    json扩展参数(备用,目前不需要)
  * @param[in] cb                操作结果回调, nim_unsubscribe_event_cb_func回调函数定义见nim_subscribe_event_def.h
  * @param[in] user_data        APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理!
  * @return void 无返回值
  * @note 错误码    200:成功
  *                414:参数错误
  *                500:未知错误
  */
NIM_SDK_DLL_API void nim_unsubscribe_event(int event_type, const char *accid_list_json, const char *json_extension, nim_unsubscribe_event_cb_func cb, const void *user_data);

/** @fn void nim_batch_unsubscribe_event(int event_type, const char *json_extension, nim_batch_unsubscribe_event_cb_func cb, const void *user_data)
  * 取消指定事件的全部订阅关系
  * @param[in] event_type        事件类型
  * @param[in] json_extension    json扩展参数(备用,目前不需要)
  * @param[in] cb                操作结果回调, nim_batch_unsubscribe_event_cb_func回调函数定义见nim_subscribe_event_def.h
  * @param[in] user_data        APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理!
  * @return void 无返回值
  * @note 错误码    200:成功
  *                414:参数错误
  *                500:未知错误
  */
NIM_SDK_DLL_API void nim_batch_unsubscribe_event(int event_type, const char *json_extension, nim_batch_unsubscribe_event_cb_func cb, const void *user_data);

查询订阅关系

可以查询指定好友的事件订阅信息,也可以查询指定类型的事件订阅信息。

/** @fn void nim_query_subscribe_event(int event_type, const char *accid_list_json, const char *json_extension, nim_query_subscribe_event_cb_func cb, const void *user_data)
  * 按账号查询指定事件订阅关系
  * @param[in] event_type        事件类型
  * @param[in] accid_list_json    用户列表,例 ["litianyi01", "litianyi02", ...]
  * @param[in] json_extension    json扩展参数(备用,目前不需要)
  * @param[in] cb                操作结果回调, nim_query_subscribe_event_cb_func回调函数定义见nim_subscribe_event_def.h
  * @param[in] user_data        APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理!
  * @return void 无返回值
  * @note 错误码    200:成功
  *                414:参数错误
  *                500:未知错误
  */
NIM_SDK_DLL_API void nim_query_subscribe_event(int event_type, const char *accid_list_json, const char *json_extension, nim_query_subscribe_event_cb_func cb, const void *user_data);

/** @fn void nim_batch_query_subscribe_event(int event_type, const char *json_extension, nim_batch_query_subscribe_event_cb_func cb, const void *user_data)
  * 查询指定事件的全部订阅关系
  * @param[in] event_type        事件类型
  * @param[in] json_extension    json扩展参数(备用,目前不需要)
  * @param[in] cb                操作结果回调, nim_batch_query_subscribe_event_cb_func回调函数定义见nim_subscribe_event_def.h
  * @param[in] user_data        APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理!
  * @return void 无返回值
  * @note 错误码    200:成功
  *                414:参数错误
  *                500:未知错误
  */
NIM_SDK_DLL_API void nim_batch_query_subscribe_event(int event_type, const char *json_extension, nim_batch_query_subscribe_event_cb_func cb, const void *user_data);