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