Getting started with C++ C++

This guide will be a brief introduction to using the deepstream C++ client with deepstreamHub.

At present, the deepstream APIs that the C++ client supports are:

• Events
• Presence

Create a free account and get your API key

Connect to deepstreamHub and log in

From your project's directory, fetch the deepstream C++ client SDK from GitHub:

git clone git@github.com:deepstreamIO/deepstream.io-client-cpp.git
cd deepstream.io-client-cpp

and follow the instructions in README.md to install the necessary dependencies for your system and build the client.

Now, back in the our application, we can include libdeepstream:

#include <deepstream.hpp>

Now you can get your app url from the dashboard and establish a connection to deepstreamHub and log in (we haven't yet configured authentication, so there are no credentials required). Here we use lambda syntax to pass in a deepstream::LoginCallback that will be called upon successful login.

deepstream::Deepstream client("<YOUR APP URL>");
client.login([](const json &&user_data) {
    std::cout << "Client logged in with user data: " << user_data << std::endl;
});

The client uses a polling websocket library, so you'll need to make a call to client.process_messages inside an event loop, to so that the client can read and service any messages that are in the queue:

while (/* still running */) {
  client.process_messages();
  // other application logic
  usleep(1000);
}

The deepstream client includes and uses Niels Lohmann's JSON library for data interchange. Documentation for the library is available here.

This using directive simply allows us to refer to JSON objects without explicitly providing a deepstream:: or nlohmann:: prefix:

using deepstream::json;

Events (publish-subscribe)

Clients can subscribe to events using client.event.subscribe:

client.event.subscribe("test-event", [&](const json &event_data) {
  // print out the event data
  std::cout << "test event: " << event_data << std::endl;
});

Whenever an event is emitted, the given function is called with the payload and publish events using .emit

json data = { { "some", "data" } } // this syntax constructs the JSON object {"some": "data"}
client.event.emit("test-event", data );

To stop receiving event updates, we can call client.event.unsubscribe:

client.event.unsubscribe("test-event");

Presence

You can fetch a list of authenticated users using client.presence.get_all. This method takes a callback QueryFn which accepts a std::vector of usernames:

client.presence.get_all([](const std::vector<std::string> users){
  // print out the list of logged-in users
  std::cout << "Users: " << std::endl;
  for (const std::string &user : users) {
    std::cout << "\t" << user << std::endl;
  }
}

client.presence.subscribe([&](const std::string &name, bool online) {
  // print out a status update e.g. "Eli has come online"
  std::cout << name << (online ? " has come online" : " has disconnected") << std::endl;
});

Unsubscribing from updates is simple:

client.presence.unsubscribe();