Overview

Welcome to the Device Data Hub C API documentation.

This library provides a C interface for interacting with Device Data Hub. Applications using this library can manage topics, produce data, and consume data.

Getting Started

Device Data Hub Core is the central data hub on Axis devices. Platform applications or ACAPs can produce data to and consume data from Device Data Hub Core.

For more information about Device Data Hub, see Device Data Hub documentation.

The library has the following main components to interact with Device Data Hub:

• Client - Manages connection to Device Data Hub and creates writers/subscribers
  • DHClient - Opaque client handle
  • dh_client_create() - Creates a new client instance
  • dh_client_connect() - Connects to Device Data Hub
  • dh_client_disconnect() - Disconnects from Device Data Hub
  • dh_client_destroy() - Destroys client and frees resources
• Writer - Publishes data to topics
  • DHWriter - Opaque writer handle for any topic
  • dh_writer_write_data() - Writes data to topics
  • dh_writer_create_instance() / dh_writer_delete_instance() - Manages instances
• Subscriber - Receives data from topics via callbacks
  • DHSubscriber - Subscriber for one or more topics
  • dh_subscriber_subscribe() - Subscribes to topic data
  • Callback-based data reception via dh_subscriber_set_data_callback() / dh_subscriber_set_topic_update_callback() / dh_subscriber_set_instance_update_callback()

Available topics can be found at Topic List page.

Examples of how to use Device Data Hub C Client library can be found at acap-native-sdk-examples.

JSON Data Format

Device Data Hub C API uses JSON format for topic data. The API will accept and provide JSON strings through the DHTopicData type. Applications can use the provided functions:

• dh_topic_data_get_json_data() - Get JSON string from DHTopicData
• dh_topic_data_set_json_data() - Update DHTopicData with new JSON

Applications can work with JSON strings directly or use 3rd party C libraries (Jansson, cJSON, json-c, etc.) to create easy conversion from/to C data structures.

Error Handling

The C API uses a consistent error handling pattern:

• Functions that can fail return bool (true on success, false on failure)
• On failure, error details are provided via an output DHError** parameter
• Errors must be freed with dh_error_destroy()
• Error details can be accessed via:
  • dh_error_get_code() - Get error code enum
  • dh_error_get_message() - Get human-readable message
  • dh_error_to_string() - Get formatted error string

Callback Threading

All callbacks (connection state updates, data reception, consumer match notifications) are executed on internal library threads. Applications should:

• Keep callback processing lightweight and fast
• Ensure callback implementations are thread-safe
• Avoid blocking operations in callbacks
• Copy data if needed for later processing outside the callback