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 #

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

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

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

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

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;
}

Edit this page on Github