Notification management

Brief description

The Kaa Notifications subsystem enables messages delivery from the Kaa cluster to endpoints (EP). It is based on auto-generated classes according to the topic's notification schema used during SDK generation.

Notification topics can be mandatory or optional. Mandatory topic notifications are delivered in an enforced manner. Optional topics require subscription.

It is the responsibility of the client code to register the topic update listener and subscribe to optional topics.

Topics - usage examples

Get available topics

using namespace kaa;

IKaaClient& kaaClient = Kaa::getKaaClient();
const auto& topics = kaaClient.getTopics();

for (const auto it : topics) {
    std::cout << "Id: " << it.first << ", name: " << it.second.name
              << ", type: " << LoggingUtils::TopicSubscriptionTypeToString(
                      it.second.subscriptionType) << std::endl;
}

Updates on available topics

To receive updates on available topics, do the following:

#include "kaa/notification/INotificationTopicListListener.hpp"

class BasicTopicUpdateListener : public INotificationTopicListListener {
public:
    // Callback is used when the new list of available topics is received. 
    virtual void onListUpdated(const Topics& newList) {
        for (const auto& topic : newList) {
            std::cout << "Id: " << topic.id << ", name: " << topic.name
                      << ", type: " << LoggingUtils::TopicSubscriptionTypeToString(topic.subscriptionType) << std::endl;
        }
    }
};
...
// Add listener to receive updates on available topics.
std::unique_ptr<BasicTopicUpdateListener> topicUpdateListener(new BasicTopicUpdateListener);
kaaClient.addTopicListListener(*topicUpdateListener);
...
// Remove the topic listener.
kaaClient.removeTopicListListener(*topicUpdateListener);

Notifications - usage examples

Assume, the notification schema has the following form:

{
    "type": "record",
    "name": "BasicNotification",
    "namespace": "org.kaaproject.kaa.client.example",
    "fields": [
        {
            "name": "body",
            "type": "string"
        }
    ]
}

After calling avrogen.sh script Avro C++ compiler will be generated appropriate code and put it into NotificationGen.hpp header. So auto-generated notification class will be like:

struct BasicNotification {
    std::string body;
};

General topic's notification listener(s)

To receive notifications both on mandatory or on optional topics, do the following:

#include "kaa/notification/INotificationListener.hpp"

class BasicNotificationListener : public INotificationListener {
public:
    virtual void onNotification(const std::string& id, const KaaNotification& notification) {
        std::cout << "Received notification with body: " << notification.body << std::endl;
    }
};
...
std::unique_ptr<BasicNotificationListener> generalNotificationListener(new BasicNotificationListener);

// Add the general listener.
kaaClient.addNotificationListener(*generalNotificationListener);
...
// Remove the general listener.
kaaClient.removeNotificationListener(*generalNotificationListener);

Topic specific notification listener(s)

To receive notifications on the specified topic, do the following:

#include "kaa/notification/INotificationListener.hpp"

class WeatherNotificationListener : public INotificationListener {
public:
    virtual void onNotification(const std::string& id, const KaaNotification& notification) {
        std::cout << "What's weather: " << notification.body << std::endl;
    }
};

class NewsNotificationListener : public INotificationListener {
public:
    virtual void onNotification(const std::string& id, const KaaNotification& notification) {
        std::cout << "What's news: " << notification.body << std::endl;
    }
};

// Add specific listeners both for news and weather topics
std::unique_ptr<WeatherNotificationListener> weatherTopicListener(new WeatherNotificationListener);
std::unique_ptr<NewsNotificationListener> newsTopicListener(new NewsNotificationListener);

// Add listener
kaaClient.addNotificationListener("weather_topic_id", *weatherTopicListener);
kaaClient.addNotificationListener("news_topic_id", *newsTopicListener);
...
// Remove listener
kaaClient.removeNotificationListener("weather_topic_id", *weatherTopicListener);
kaaClient.removeNotificationListener("news_topic_id", *newsTopicListener);

Subscription to optional topics

To receive notifications on the optional topic, do the following:

kaaClient.subscribeToTopic("optional_topic_id");

To stop receiving notifications on the optional topic, do the following:

kaaClient.unsubscribeFromTopic("optional_topic_id");

There are similar routines to deal with the group of optional topics: kaa::INotificationManager::subscribeToTopics() and kaa::INotificationManager::unsubscribeFromTopics() .

Subscription postponing

There is an ability to postpone subscription requests. It is a convenient way to do several subscription changes.
Consider the example:

// Do subscription changes with the false value for the forceSync parameter.
kaaClient.subscribeToTopics({"optional_topic1", "optional_topic2", "optional_topic3"}, false);
kaaClient.unsubscribeFromTopic("optional_topic4", false);

// Add notification listener(s) (optional).

// Send subscription requests.
kaaClient.syncTopicSubscriptions();