Ditto

API Reference Documentation

This is the API reference documentation for the Ditto C++ SDK.

For more information, see the Quickstart guide and installation guides.

Take a look at the classes available in the SDK: Class Index.

Example

This program displays the contents of a tasks collection, printing new values whenever an update is received from another peer.

#include "Ditto.h"
 
#include <chrono>
#include <cstdlib>
#include <exception>
#include <filesystem>
#include <iostream>
#include <mutex>
#include <string>
#include <thread>
 
// Create an application at <https://portal.ditto.live/> and copy the values for
// App ID, Auth URL, Websocket URL, and Online Playground Token here.
constexpr const char *DITTO_APP_ID = "replace with your app ID";
constexpr const char *DITTO_AUTH_URL = "replace with your authorization URL";
constexpr const char *DITTO_WEBSOCKET_URL = "replace with your websocket URL";
constexpr const char *DITTO_ONLINE_PLAYGROUND_TOKEN =
    "replace with your playground token";
 
constexpr const char *PERSISTENCE_DIR = "/tmp/ditto-cpp-testapp";
constexpr const char *LOG_EXPORT_PATH = "./ditto-logexport.jsonl.gz";
 
// Write Ditto log to LOG_EXPORT_PATH
void export_ditto_log() noexcept {
  try {
    if (std::filesystem::exists(LOG_EXPORT_PATH)) {
      std::filesystem::remove(LOG_EXPORT_PATH);
    }
    ditto::Log::export_to_file(LOG_EXPORT_PATH).get();
    std::cerr << "info: exported log to " << LOG_EXPORT_PATH << std::endl;
  } catch (const std::exception &err) {
    std::cerr << "error: unable to export log dump: " << err.what()
              << std::endl;
  }
}
 
int main(int argc, const char **argv) {
  try {
    std::cerr << "info: running Ditto test app with SDK version "
              << ditto::Ditto::get_sdk_version() << std::endl;
 
    // Suppress non-error log messages
    ditto::Log::set_minimum_log_level(ditto::LogLevel::warning);
 
    // Create an identity for the online playground
    const auto identity = ditto::Identity::OnlinePlayground(
        DITTO_APP_ID, DITTO_ONLINE_PLAYGROUND_TOKEN, false, DITTO_AUTH_URL);
 
    // Create a Ditto instance with the identity and persistence directory
    auto config = ditto::Ditto::Config::default_config()
                      .set_identity(identity)
                      .set_persistence_directory(PERSISTENCE_DIR);
    auto ditto = ditto::Ditto::open(config);
 
    // Enable peer-to-peer communication and set the websocket URL
    ditto->update_transport_config([](ditto::TransportConfig &config) {
      config.enable_all_peer_to_peer();
      config.connect.websocket_urls.insert(DITTO_WEBSOCKET_URL);
    });
 
    // Disabling sync with Ditto v3 peers is required for use of DQL (Ditto Query Language)
    ditto->disable_sync_with_v3();
 
    ditto->start_sync();
 
    // Use a mutex to synchronize console output from multiple threads
    std::mutex mtx;
 
    // Register a function to be called whenever there is new data
    auto observer = ditto->get_store().register_observer(
        "SELECT * FROM tasks WHERE isDeleted = false",
        [&](ditto::QueryResult query_result) {
          const auto items = query_result.items();
          std::lock_guard<std::mutex> lock(mtx);
          std::cout << "Update for collection 'tasks':\n";
          for (const auto &item : items) {
            std::cout << "  " << item.json_string() << "\n";
          }
          std::cout << "End of update for collection 'tasks'\n";
        });
 
    // Subscribe to changes from other peers
    auto subscription =
        ditto->get_sync().register_subscription("SELECT * FROM tasks");
 
    // Main thread sleeps for 15 seconds to allow the observer to receive data
    // and print it to the console, then exits the program.
    {
      std::lock_guard<std::mutex> lock(mtx);
      std::cout << "(Waiting for 15 seconds...)" << std::endl;
    }
    std::this_thread::sleep_for(std::chrono::seconds(15));
 
    // Clean up
    subscription->cancel();
    observer->cancel();
    ditto->stop_sync();
 
    export_ditto_log();
  } catch (const std::exception &e) {
    // On an exception, print the error message and export the log
    std::cerr << "error: " << e.what() << std::endl;
    export_ditto_log();
    std::exit(EXIT_FAILURE);
  }
 
  return 0;
}