Meet the Diffusion C API

A recent release of Diffusion Cloud added C to the list of APIs we provide for users of our cloud service. We’re pretty excited about this and here’s why.

C is one of the most versatile and enduring programming languages. It’s not hard to see why: it’s universally available, has no platform or vendor lock-in, it’s fast to start, has low system system requirements and memory footprint, and allows you access to all your machine’s resources and libraries. It’s these characteristics that make C and the Diffusion C API perfect for your embedded or IoT devices.

Interested? Let’s meet the Diffusion C API.

The Diffusion C client library is provided ready compiled for the following platforms:

• Linux (64-bit)
  RedHat and Centos 6.5 or later. Provided as both a dynamically and a statically linked library.
• Windows (32-bt or 64-bit)
  Version 7 or later, with the Visual C Compiler from Visual Studio 2013 or later. Provided as a statically linked library.
• OS X (64-bit)
  Xcode7.1 or later. Provided as a statically linked library.

Need it compiled for something else? You can always ask us: [email protected] We can’t promise everything, but it never hurts to ask!

It comes packed with features:

• Subscribe to topics to receive updates
• Create topics and publish to them
• Authenticate other clients’ connections
• Send messages to specific client sessions
• Update security and authentication information held on Diffusion Cloud
• And much more, see our manual for details.

Start developing

Before you get started, there are a few dependencies that you’ll need on your development machine:

• Apache Portable Runtime version 1.5 with APR-util library
• Perl Compatible Regular Expressions library, version 8.3
• OpenSSL library, version 1.0.2a

• libwebsockets library, version 1.6.0

The Windows version of our C client library has these libraries already packaged in – and we recommend you use the ones we provide rather than your own. But for Linux and OS X, you can get these dependencies through your package manager.

Let’s have a look at the basics:

Including the diffusion.h header file, pulls in the rest of the required files.

#include "diffusion.h"

Connecting to Diffusion Cloud takes just three lines of code:

SESSION_T *session; 
DIFFUSION_ERROR_T error; 
session = session_create(url, username, password, NULL, NULL, &error);

The URL you use to connect consists of the transport you want to use – either WebSocket (ws://) or secure WebSocket (wss://); the host of your Diffusion Cloud service, which you can find on your Diffusion Cloud dashboard; and the port to connect on – 80 for regular connections and 443 for secure connections. Here’s an example ws://tracingBothFoster.us.diffusion.cloud:80.
The username you use to connect must have roles with sufficient permissions to perform any actions you want you client to take. For example, if your client is updating topics, it needs the TOPIC_CONTROL role.

The add_topic method creates a new topic on Diffusion Cloud:

const TOPIC_DETAILS_T *string_topic_details =        
          create_topic_details_single_value(M_DATA_TYPE_STRING); 
const ADD_TOPIC_PARAMS_T add_topic_params = { 
              .topic_path = “my_topic”, 
              .details = string_topic_details, 
              .on_topic_added = on_topic_added, 
              .on_topic_add_failed = on_topic_add_failed, 
              .on_discard = on_topic_add_discard, 
};

add_topic(session, add_topic_params);

The Diffusion API is an asynchronous API. As you can see from the code snippet above, you need to create handlers elsewhere in your code that handle the events that occur when adding a topic.

Register an update source to send your updates from with the register_update_source method. Again you need to create the required handlers for this action’s events.

const UPDATE_SOURCE_REGISTRATION_PARAMS_T update_reg_params = { 
        .topic_path = “my_topic”,
        .on_init = on_update_source_init, 
        .on_registered = on_update_source_registered, 
        .on_active = on_update_source_active, 
        .on_standby = on_update_source_standby,
        .on_close = on_update_source_closed 
};

// Register an updater 
const CONVERSATION_ID_T *updater_id = 
           register_update_source(session, update_reg_params);

Unlike some of our other APIs, the C API does not currently allow you to update a topic non-exclusively. To update a topic from C, you must register an update source.

Use your update source and the update method to update a topic with some content:

UPDATE_T *upd = update_create(UPDATE_ACTION_REFRESH, UPDATE_TYPE_CONTENT, “Hello World!”); 
UPDATE_SOURCE_PARAMS_T pdate_source_params = { 
        .update = upd,
        .updater_id = updater_id, 
        .topic_path = topic_name, 
        .on_success = on_update_success,
        .on_failure = on_update_failure 
};
update(session, update_source_params);

These few basics are pretty much all you need to start streaming data from a C client to your Diffusion Cloud topics. A full example of a publishing client is available in the manual, along with many more demonstrations of the C API in action.

These examples are ready to build and use. Just a couple of notes about building C clients to use with Diffusion Cloud: Make sure you link to our library and make sure you link against all of the dependencies – apr , apr-util , pcre, openssl, and libwebsockets. That’s all you need.

Happy developing!

Want to see how easy it is to get started with Diffusion Cloud? Sign up for a free demo.