SDK
SDK C++ v1.x
1

You are currently looking at the documentation of a previous version of Kuzzle. We strongly recommend that you use the latest version. You can also use the version selector in the top menu.

This SDK has been deprecated because of stability issues. It is not advised to use it in a production environment.

subscribe #

Subscribes by providing a set of filters: messages, document changes and, optionally, user events matching the provided filters will generate real-time notifications, sent to you in real-time by Kuzzle.

Signature #

Copied to clipboard!
std::string subscribe(
    const std::string& index,
    const std::string& collection,
    const std::string& filters,
    kuzzleio::NotificationListener* listener);

std::string subscribe(
    const std::string& index,
    const std::string& collection,
    const std::string& filters,
    kuzzleio::NotificationListener* listener,
    const kuzzleio::room_options& options);

Arguments #

Arguments Type Description
index
const std::string&
Index name
collection
const std::string&
Collection name
filters
const std::string&
JSON string representing a set of filters following Koncorde syntax
listener
kuzzleio::NotificationListener*
Listener function to handle notifications
options
kuzzleio::room_options*
Subscription options

listener #

Listener function that will be called each time a new notifications is received. The listener will receive a const kuzzleio::notification_result* as only argument.

options #

Additional subscription options.

Property Type
(default)
Description
scope
const char*

(all)
Subscribe to document entering or leaving the scope
Possible values: all, in, out, none
users
const char*

(none)
Subscribe to users entering or leaving the room
Possible values: all, in, out, none
subscribeToSelf
bool

(true)
Subscribe to notifications fired by our own queries
volatile
const char*

(null)
JSON string representing subscription information, used in user join/leave notifications

Return #

The room ID.

Exceptions #

Throws a kuzzleio::KuzzleException if there is an error. See how to handle error.

Usage #

Simple subscription to document notifications

Copied to clipboard!
kuzzleio::NotificationListener listener =
  [](const std::shared_ptr<kuzzleio::notification_result> &notification) {
    std::string id = notification->result->id;
    if (notification->scope == std::string("in")) {
      std::cout << "Document " << id << " enter the scope" << std::endl;
    } else {
      std::cout << "Document " << id << " leave the scope" << std::endl;
    }
  };
try {
  // Subscribe to notifications for documents containing a 'name' property
  std::string filters = R"({ "exists": "name" })";
  kuzzle->realtime->subscribe("nyc-open-data", "yellow-taxi", filters, &listener);
  // Create a document matching the provided filters
  kuzzle->document->create(
    "nyc-open-data",
    "yellow-taxi",
    "nina-vkote",
    R"({ "name": "nina vkote", "age": 19 })");
} catch (kuzzleio::KuzzleException &e) {
  std::cerr << e.what() << std::endl;
}

Subscription to document notifications with scope option

Copied to clipboard!
kuzzleio::NotificationListener listener =
  [](const std::shared_ptr<kuzzleio::notification_result> &notification) {
    std::cout << "Document moved " << notification->scope << " from the scope" << std::endl;
  };
try {
  // Subscribes to notifications when document leaves the scope
  std::string filters = R"({ "range": { "age": { "lte": 20 } } })";
  kuzzleio::room_options options;
  options.scope = "out";
  kuzzle->realtime->subscribe(
    "nyc-open-data",
    "yellow-taxi",
    filters,
    &listener,
    options);
  // Creates a document who is in the scope
  kuzzle->document->create(
    "nyc-open-data",
    "yellow-taxi",
    "nina-vkote",
    R"({ "name": "nina vkote", "age": 19 })");
  // Update the document so he isn't in the scope anymore
  // we shall receive a notification
  kuzzle->document->update(
    "nyc-open-data",
    "yellow-taxi",
    "nina-vkote",
    R"({ "age": 42 })");
} catch (kuzzleio::KuzzleException &e) {
  std::cerr << e.what() << std::endl;
}

Subscription to message notifications

Copied to clipboard!
kuzzleio::NotificationListener listener =
  [](const std::shared_ptr<kuzzleio::notification_result> &notification) {
    std::cout << "Message notification received" << std::endl;
    std::cout << notification->result->content << std::endl;
    // { "metAt": "Insane", "hello": "world" }
  };
try {
  // Subscribes to notifications for documents
  kuzzle->realtime->subscribe("i-dont-exist", "in-database", "{}", &listener);
  std::string message = R"({ "metAt": "Insane", "hello": "world" })";
  kuzzle->realtime->publish("i-dont-exist", "in-database", message);
} catch (kuzzleio::KuzzleException &e) {
  std::cerr << e.what() << std::endl;
}

Subscription to user notifications

Copied to clipboard!
kuzzleio::NotificationListener listener =
  [](const std::shared_ptr<kuzzleio::notification_result> &notification) {
    std::cout << "Currently " << notification->result->count << " users in the room" << std::endl;
    std::cout << notification->volatiles << std::endl;
    // "{ "username": "nina vkote" }"
  };
try {
  // Subscription to notifications and notifications when user join or leave
  const char *filters = R"({ "exists": "name" })";
  kuzzleio::room_options options;
  options.users = "all";
  kuzzle->realtime->subscribe(
    "nyc-open-data",
    "yellow-taxi",
    filters,
    &listener,
    options);
  // Instantiates a second kuzzle client:
  //  multiple subscriptions made by the same user
  //  will not trigger "new user" notifications
  kuzzleio::WebSocket* ws2 = new kuzzleio::WebSocket("kuzzle");
  kuzzleio::Kuzzle* kuzzle2 = new kuzzleio::Kuzzle(ws2);
  kuzzle2->connect();
  // Set some volatile data
  kuzzleio::room_options options2;
  options2.volatiles = R"({ "username": "nina vkote" })";
  // Subscribe to the same room with the second client
  kuzzle2->realtime->subscribe(
    "nyc-open-data",
    "yellow-taxi",
    filters,
    &listener,
    options2);
} catch (kuzzleio::KuzzleException &e) {
  std::cerr << e.what() << std::endl;
}