CloudPlugs ANSI C Client Library

Table of Contents

• The CloudPlugs IoT Platform
• Library Guide
  • Requirements
  • Usage
  • Configuration
  • Execute Rest HTTP requests

CloudPlugs REST Client for ANSI C is a library to perform HTTP requests to CloudPlugs servers. The official repository is: https://github.com/cloudplugs/rest-c

The CloudPlugs IoT Platform

Cloudplugs is a cloud based IoT platform to enable the fast prototyping, connection, deployment and management of smart "Things" (sensors, smartphones, home appliances, etc.). Different objects can interact with each other by publishing and/or reading any type of data on shared channels through simple communication protocols. You can learn more at http://www.cloudplugs.com/how-it-works/ and you can sign-up on http://www.cloudplugs.com/register to start connecting your Things.

Library Guide

Requirements

List of external libraries to be included:

• Libcurl (http://curl.haxx.se/ ): to manage HTTP connections.
  
• Jansson (https://github.com/akheron/jansson): This library is optional, but necessary if you want the library to manage encoding/decoding of JSON data on your behalf. (Please use version 2.5 or greater)
  

Usage

The library provides a set of configuration options, and the functionalities to perform HTTP requests to Cloudplugs server. According to Cloudplugs Rest Api documentation, the body of HTTP request must be a JSON encoded string containing request's parameters. For this reason the library provides two functions for each request:

• One function (identified by the "_json" suffix) allows to pass request parameters explicitelly as parameters of the function itself. In this case the parameters will be parsed and encoded in a JSON string automatically by the library and the result will be returned as a Jansson JSON object. (Jansson library is required, see Requirements)

  #include "cp_rest_json.h"

• Another function with the entire HTTP request body passed as a string in the function's parameters (please refer to Cloudplugs Rest API to learn about requests and parameters.). The effort to manage JSON encoding/decoding data is left to you.

  #include "cp_rest.h"

Include other dependencies:

#include <time.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>

Create a new session and initialize the data required:

cp_session cps = cloudplugs_create_session();

Now you are ready to configure the library and invoke functions to perform REST requests to the server!

Finally close and clean the session:

cloudplugs_destroy_session(cps);

Configuration

There are a few configuration parameters available for customization (if needed) before invoking any request. This parameters are:

• timeout: the timeout value for HTTP requests
  
• auth id: the authentication identifier
  
• auth pass: the authentication password
  
• auth master: true to authenticate using the main account password
  
• base url: base URL for HTTP requests
  
• enable SSL : switch SSL mode on/off
  
  Example:

  cloudplugs_set_auth(cps, "youAuthID", "yourPassword", CP_TRUE);

Execute Rest HTTP requests

After completing the configuration, you can execute HTTP requests to the server by invoking any of the request functions. All the requests are synchronous and are executed per the Cloudplugs Rest API documentation. For example:

cp_res res_code;
res_code = cloudplugs_set_device_prop(cps, NULL, NULL, "{\"prop1\" : \"lorem ipsum\", \"prop2\" : true }");
char* res = NULL;
size_t res_len;
res_code = cloudplugs_get_device_prop(cps, NULL, NULL, &res, &res_len);

Or, if using the Jansson JSON library :

cp_res res_code;
json_t* sprop = json_integer(123);
res_code = cloudplugs_set_device_prop_json(cps, NULL, "myPropertyName", sprop);
json_t* json_res;
res_code = cloudplugs_get_device_prop_json(cps, NULL, NULL, &res);