why deepstreamHub? compare us getting started feature roadmap faq
use cases pricing
products
developers
company
blog contact

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

Important

  • Note: The C++ client is currently in beta and is therefore subject to change, with new features being added over time. We recommend checking the README for up-to-date information on the installation process and feature support. As usual if you find a bug or need help getting the client to build on your architecture, please feel free to create an issue on the client GitHub repository or get in touch through one of our other support channels.

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.

Info

  • You can see the code for this example application in the file /examples/ds-example.cpp within the client repository. There is also an example CMake configuration in /examples/CMakeLists.txt that shows how to link against the correct dependencies for the build to succeed.

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)

Events are deepstreamHub’s publish-subscribe mechanism. Clients and backend processes can subscribe to event-names (sometimes also called “topics” or “channels”) and receive messages published by other endpoints.

Events are non-persistent, one-off messages. For persistent data, please use records.

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();