Event subscription

Event subscription allows users to subscribe the events published by other users. A subscriber will be notified of any event published by that user. There are two types of events: system predefined event and custom event, of which the former falls within the range of 1-99999, and the latter must have a value larger than 99999. For custom events, users can specify different event types and events to define different meanings as needed; for system predefined events, the system reserves the event value from 1 to 9999. If users want to send a system predefined event , the value of which must be greater than 9999. Currently, system predefined events are limited to on-line status events, the event value of which is 1. When the user logs in, logs out, and leaves abnormally, the server will send a corresponding on-line status event value to notify the subscriber.Subscribing or un-subscribing events with one client will take effect on other clients at the same time Therefore, it is required to unsubscribe events with caution in a manner that prevents any effect on other clients.

Receiving events

Register the callback feature for receiving events in advance, so that it can receive the subscribed event after the account is logged in. Two callback features need to be registered: One for receiving a subscribed event, the other for receiving multiple subscribed events.

Sample codes:

C++

void OnPushEventCallback(nim::NIMResCode res_code, const nim::EventData& event_data)
{	
	if (res_code == nim::kNIMResSuccess)
	{
		...
	}
}

void :OnBatchPushEventCallback(nim::NIMResCode res_code, const std::list<nim::EventData>& event_list)
{
	if (res_code == nim::kNIMResSuccess)
	{
		...
	}
}

std::string foo()
{
	nim::SubscribeEvent::RegPushEventCb(&OnPushEventCallback);
	nim::SubscribeEvent::RegBatchPushEventCb(&OnBatchPushEventCallback);
));
}

C#

...

C

void CallbackPushEvent(int res_code, const char *event_info_json, const char *json_extension, const void *user_data)
{
	if (user_data)
	{
		...
	}
}

void CallbackBatchPushEvent(int res_code, const char *event_list_json, const char *json_extension, const void *user_data)
{
	if (user_data)
	{
		...
	}
}

typedef void(*nim_subscribe_event_reg_push_event_cb)(const char *json_extension, nim_push_event_cb_func cb, const void *user_data);
typedef void(*nim_subscribe_event_reg_batch_push_event_cb)(const char *json_extension, nim_batch_push_event_cb_func cb, const void *user_data);

void foo()
{
	nim_subscribe_event_reg_push_event_cb func = (nim_subscribe_event_reg_push_event_cb) GetProcAddress(hInst, "nim_subscribe_event_reg_push_event_cb");
	nim_subscribe_event_reg_batch_push_event_cb batch_func = (nim_subscribe_event_reg_batch_push_event_cb) GetProcAddress(hInst, "nim_subscribe_event_reg_batch_push_event_cb");

	func(nullptr, &CallbackPushEvent, nullptr);
	batch_func(nullptr, &CallbackBatchPushEvent, nullptr);
}

Publishing events

Users can publish system predefined events or custom events based on their own needs. To publish an event, the user needs to specify its type, event value, message id, validity period, broadcast type, synchronization type, and choose whether to attach custom extended properties to the event as required. Among them Event validity period: 60 seconds to 7 days, in seconds, validity period refers to the time period during which the corresponding event can be received after login; broadcast type specifies whether to notify offline subscribers; synchronization type specifies whether to synchronize the event to other clients used; and extended properties can contain any string created as needed.

Sample codes:

C++

void EventCallback(nim::NIMResCode res_code, int event_type, const nim::EventData& event_data)
{
	...
}

std::string foo()
{
	nim::EventData event_data;
	event_data.event_type_ = nim::kNIMEventTypeOnlineState;
	event_data.event_value_ = nim::kNIMEventOnlineStateValueUpdateConfig;
	event_data.client_msg_id_ = local message id;
	event_data.ttl_ = 7*24*60*60;
	event_data.broadcast_type_ = nim::kNIMEventBroadcastTypeAll;
	event_data.sync_self_ = nim::kNIMEventSyncTypeSelf;

	nim::SubscribeEvent::Publish(event_data, &EventCallback);
}

C#

...

C

void CallbackPublishEvent(int res_code, int event_type, const char *event_info_json, const char *json_extension, const void *user_data)
{
	if (user_data)
	{
		...
	}
}

typedef void(*nim_publish_event)(const char *event_json, const char *json_extension, nim_publish_event_cb_func cb, const void *user_data);

void foo()
{
	nim_publish_event func = (nim_publish_event) GetProcAddress(hInst, "nim_publish_event");

	Json::FastWriter fs;
    Json::Value values;
	values[kNIMEventEventType] = nim::kNIMEventTypeOnlineState;
	values[kNIMEventEventValue] = nim::kNIMEventOnlineStateValueCustom + 1;
	values[kNIMEventMsgIdClient] = local message id;
	values[kNIMEventConfig] = config_;
	values[kNIMEventTTL] = 7*24*60*60;
	values[kNIMEventBroadcastType] = nim::kNIMEventBroadcastTypeAll;
	values[kNIMEventSyncSelf] = nim::kNIMEventSyncTypeSelf;
    std::string json_value = fs.write(values);

	func(json_value.c_str(), nullptr, &CallbackPublishEvent, nullptr);
}

Subscribing to events

To receive an event published by a user, you must first subscribe to one of his/her events. When subscribing to events, you need to specify the event type, validity period of subscription, and whether to synchronize the latest events immediately after subscription. Among them Subscription validity period: 60 seconds to 30 days, in seconds. Upon expiration of validity period, re-subscription is required to continue receiving the event.

Sample codes:

C++

void EventCallback(nim::NIMResCode res_code, int event_type, const std::list<std::string>& faild_list)
{
	...
}

std::string foo()
{
	std::list<std::string> subscribe_list;
	subscribe_list.push_back("test1");
	subscribe_list.push_back("test2");

	nim::SubscribeEvent::Subscribe(nim::kNIMEventTypeOnlineState,
		1*24*60*60,
		nim::kNIMEventSubscribeSyncTypeSync,
		subscribe_ids,
		&EventCallback,
	);
}

C#

...

C

void CallbackSubscribe(int res_code, int event_type, const char *faild_list_json, const char *json_extension, const void *user_data)
{
	...
}

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

void foo()
{
	Json::FastWriter fs;
    Json::Value value;
    value.append("test1");
	value.append("test2");
    std::string json_value = fs.write(value);

	nim_subscribe_event func = (nim_subscribe_event) GetProcAddress(hInst, "nim_subscribe_event");
	func(nim::kNIMEventTypeOnlineState,
	1*24*60*60,
	nim::kNIMEventSubscribeSyncTypeSync,
	json_value.c_str(),
	nullptr,
	&CallbackSubscribe,
	nullptr);
}

Unsubscribing from events

Sample codes:

C++

void EventCallback(nim::NIMResCode res_code, int event_type, const std::list<std::string>& faild_list)
{
	...
}

std::string foo()
{
	std::list<std::string> unsubscribe_list;
	unsubscribe_list.push_back("test1");
	unsubscribe_list.push_back("test2");

	nim::SubscribeEvent::UnSubscribe(nim::kNIMEventTypeOnlineState, unsubscribe_ids, &EventCallback);
}

C#

...

C

void CallbackUnSubscribe(int res_code, int event_type, const char *faild_list_json, const char *json_extension, const void *user_data)
{
	...
}

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

void foo()
{
	Json::FastWriter fs;
    Json::Value value;
    value.append("test1");
	value.append("test2");
    std::string json_value = fs.write(value);

	nim_unsubscribe_event func = (nim_unsubscribe_event) GetProcAddress(hInst, "nim_unsubscribe_event");
	func(nim::kNIMEventTypeOnlineState, json_value.c_str(),	nullptr, &CallbackUnSubscribe, nullptr);
}

Unsubscribe from multiple events at a time

Sample codes:

C++

void EventCallback(nim::NIMResCode res_code, int event_type)
{
	...
}

std::string foo()
{
	nim::SubscribeEvent::BatchUnSubscribe(nim::kNIMEventTypeOnlineState, &EventCallback);
}

C#

...

C

void CallbackBatchUnSubscribe(int res_code, int event_type, const char *json_extension, const void *user_data)
{
	if (user_data)
	{
		...
	}
}

typedef void(*nim_batch_unsubscribe_event)(int event_type, const char *json_extension, nim_batch_unsubscribe_event_cb_func cb, const void *user_data);

void foo()
{
	nim_batch_unsubscribe_event func = (nim_batch_unsubscribe_event) GetProcAddress(hInst, "nim_batch_unsubscribe_event");
	func(nim::kNIMEventTypeOnlineState, nullptr, &CallbackBatchUnSubscribe, nullptr);
}

Query subscription status

Sample codes:

C++

void EventCallback(nim::NIMResCode res_code, int event_type, const std::list<nim::EventSubscribeData>& subscribe_list)
{
	...
}

std::string foo()
{
	std::list<std::string> accid_list;
	accid_list.push_back("test1");
	accid_list.push_back("test2");

	nim::SubscribeEvent::QuerySubscribe(nim::kNIMEventTypeOnlineState, accid_list, &EventCallback);
}

C#

...

C

void CallbackQuerySubscribe(int res_code, int event_type, const char *subscribe_list_json, const char *json_extension, const void *user_data)
{
	if (user_data)
	{
		...
	}
}

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

void foo()
{
	Json::FastWriter fs;
    Json::Value value;
    value.append("test1");
	value.append("test2");
    std::string json_value = fs.write(value);

	nim_query_subscribe_event func = (nim_query_subscribe_event) GetProcAddress(hInst, "nim_query_subscribe_event");
	func(nim::kNIMEventTypeOnlineState, json_value.c_str(),	nullptr, &CallbackQuerySubscribe, nullptr);
}