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, 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_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::Logger::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_version() << std::endl;
 
    // Suppress non-error log messages
    ditto::Logger::set_minimum_log_level(ditto::LogLevel::warning);
 
    // Create a Ditto instance
    auto config = ditto::Ditto::Config::default_config()
                      .set_database_id(DITTO_APP_ID)
                      .set_server_connect(DITTO_AUTH_URL)
                      .set_persistence_directory(PERSISTENCE_DIR);
    auto ditto = ditto::Ditto::open(config);
 
    // Set up authentication handler
    ditto->get_auth()->set_expiration_handler(
        [login_token = DITTO_ONLINE_PLAYGROUND_TOKEN](
            ditto::Ditto &ditto, uint32_t time_remaining) {
          try {
            ditto.get_auth()->login(
                login_token, ditto::Authenticator::get_development_provider(),
                [&](std::unique_ptr<std::string> client_info,
                    std::unique_ptr<ditto::DittoError> err) {
                  if (err != nullptr) {
                    ditto::Logger::error("expiration handler: login error:" +
                                      string(err->what()));
                  }
                });
          } catch (const std::exception &e) {
            ditto::Logger::error("expiration handler: " + string(e.what()));
          }
        });
 
    ditto->get_sync().start();
 
    // 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->get_sync().stop();
 
    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;
}