API Reference

Initialize and Authenticate

Heads Up!

You must initialize and authenticate with the ClearBlade Platform first before you perform any other functions

If you have not installed the prerequisites, please follow the tutorial @ Prerequisites. After you have installed all the prerequisites and the C SDK, include the clearblade.h header in your code: #include <clearblade.h>
Call either the initializeClearBladeUser() or initializeClearBladeDevice() function to initialize and authenticate your user with ClearBlade:

void cbInitCallback(bool error, char *result) {
  if(error) {
    printf("ClearBlade init failed %s\n", result);
    exit(-1);
  } else {
    printf("ClearBlade Init Succeeded\nAuth token: %s\n", result);
  }
}

initializeClearBladeUser(SYSTEM_KEY, SYSTEM_SECRET, PLATFORM_URL, MESSAGING_URL, USER_EMAIL, USER_PASSWORD, &cbInitCallback);

You will need to pass the function your SYSTEM_KEY, SYSTEM_SECRET, PLATFORM_URL (https://platform.clearblade.com or similar), MESSAGING_URL (tcp://platform.clearblade.com:1883 or similar), USER_EMAIL, USER_PASSWORD (or DEVICE_NAME and ACTIVE_KEY if authenticating as a device) and a function as a callback. After successful authentication, you will receive an authentication token in the callback. You can choose to store it in a variable, but the SDK stores a copy of it for itself.

MQTT Functions

Connect to the MQTT Broker

Before you connect to the MQTT Broker, make sure you include the #include "MQTTAsync.h" header in your code and link the -lpaho-mqtt3as library when you compile your code. There are two functions to choose from when connecting to the MQTT Broker with the following signatures:

connectToMQTT(char *clientId, int qualityOfService, void (*mqttOnConnect)(void* context, MQTTAsync_successData* response),
 									int (*messageArrivedCallback)(void *context, char *topicName, int topicLen, MQTTAsync_message *message))  

OR

connectToMQTTAdvanced(char *clientId, int qualityOfService, void (*mqttOnConnect)(void* context, MQTTAsync_successData* response),
 									int (*messageArrivedCallback)(void *context, char *topicName, int topicLen, MQTTAsync_message *message),
									void (*onConnLostCallback)(void *context, char *cause))

The difference between the two is that the first one does not take an onConnectionLost callback whereas the second one does. What this means is that, if for some reason, the connection to the MQTT Broker was lost and you choose the first function, the code will notify you and try to reconnect once and then leave everything to the Gods of MQTT. But if you used the second function, you will be able to handle the connection lost event and take a decision accordingly. We recommend you use the second function.
Here’s an example of how you would connect to the MQTT Broker using the connectToMQTT() function:

char *clientID = "test-client";
int qos = 0;

int messageArrived(void *context, char *topicName, int topicLen, MQTTAsync_message *message) {
  printf("Message arrived\n");
  printf("Topic: %s\n", topicName);
  char *messagePayload = malloc(message->payloadlen + 1);
  strncpy(messagePayload, message->payload, message->payloadlen);
  messagePayload[message->payloadlen] = '\0';
  printf("Message: %s\n", messagePayload);

  MQTTAsync_freeMessage(&message);
  MQTTAsync_free(topicName);
  free(messagePayload);

  return 1;
}


void onConnect(void* context, MQTTAsync_successData* response) {
  printf("Successful connection to MQTT Broker\n");
  extern int finished; // Get the 'finished' variable from the CB SDK and set it to 1 to stop the connect loop
  finished = 1;
}

connectToMQTT(clientID, qos, &onConnect, &messageArrived);

To the connectToMQTT() function, you need to pass the client-ID (string), quality of service (int), a callback to notify you of a successful connection and a callback to notify you when a message arrives on a subscription.

Note

In the onConnect callback, be sure to grab the finished variable from the C SDK using the extern keyword and set it to 1. This tells the SDK that the connect call was completed successfully and the C SDK can stop its internal loop that was waiting for the connection to complete

Now, to use the connectToMQTTAdvanced() function, use the following code as a template:

char *clientID = "test-client";
int qos = 0;

int messageArrived(void *context, char *topicName, int topicLen, MQTTAsync_message *message) {
  printf("Message arrived\n");
  printf("Topic: %s\n", topicName);
  char *messagePayload = malloc(message->payloadlen + 1);
  strncpy(messagePayload, message->payload, message->payloadlen);
  messagePayload[message->payloadlen] = '\0';
  printf("Message: %s\n", messagePayload);

  MQTTAsync_freeMessage(&message);
  MQTTAsync_free(topicName);
  free(messagePayload);

  return 1;
}


void onConnect(void* context, MQTTAsync_successData* response) {
  printf("Successful connection to MQTT Broker\n");
  extern int finished; // Get the 'finished' variable from the CB SDK and set it to 1 to stop the connect loop
  finished = 1;
}

void onConnectionLost(void *context, char *cause) {
    printf("\nConnection lost\n");
  	printf("Cause: %s\n", cause);
  	printf("Reconnecting\n");
    // If you believe that your authentication token is expired, you can reauthenticate here as follows
    initializeClearBlade(SYSTEM_KEY, SYSTEM_SECRET, PLATFORM_URL, MESSAGING_URL, USER_EMAIL, USER_PASSWORD, &cbInitCallback);
    // Here cbInitCallback is the callback you defined when you first called the initializeClearBlade() function. You can change this to another callback of your choice
    connectToMQTTAdvanced(clientID, qos, &onConnect, &messageArrived, &onConnLostCallback); // This reconnects to MQTT
}

connectToMQTTAdvanced(clientID, qos, &onConnect, &messageArrived, &onConnLostCallback);

In this case the extra argument is the OnConnectionLost callback.

Note

In the onConnect callback, be sure to grab the finished variable from the C SDK using the extern keyword and set it to 1. This tells the SDK that the connect call was completed successfully and the C SDK can stop its internal loop that was waiting for the connection to complete

Publish a message

To publish a message once a successful connection has been established to the MQTT Broker, use the publishMessage() function:

char *message = "Hello, World!!";
chat *topic = "AwesomeTopic";
int qos = 0;
int retained = 0;
publishMessage(message, topic, qos , retained);

Subscribe to a topic

To subscribe to a topic, use the subscribeToTopic() function:

char *topic = "AwesomeTopic";
int qos = 0;
subscribeToTopic(topic, qos);

Unsubscribe from a topic

To unsubscribe from a topic, use the unsubscribeFromTopic() function:

char *topic = "AwesomeTopic";
unsubscribeFromTopic(topic);

Disconnect from MQTT Broker

To disconnect your client from the MQTT Broker, call the disconnectMQTTClient() function.

Code Service Functions

You can execute a Code Service using the C SDK. There are two ways to do it, one with parameters that you want to pass to a Code Service and one without.

Execute a Code Service without parameters

To execute a Code Service without passing any parameters, use the executeCodeServiceWithoutParams() function:

char *serviceName = "TestService";

void codeServiceCallback(bool error, char *result) {
  if(error) {
    printf("Cannot execute Code Service: %s\n", result);
  } else {
    printf("Execution successful: %s\n", result);
  }
}

executeCodeServiceWithoutParams(serviceName, &codeServiceCallback);

Execute a Code Service with parameters

To execute a Code Service by passing parameters, use the executeCodeServiceWithParams() function:

char *serviceName = "TestService";
char *params = "{\"name\": \"Bubba\"}";

void codeServiceCallback(bool error, char *result) {
  if(error) {
    printf("Cannot execute Code Service: %s\n", result);
  } else {
    printf("Execution successful: %s\n", result);
  }
}

executeCodeServiceWithParams(serviceName, params, &codeServiceCallback);