C - Client APIs

This section describes how to use the basic functions available to interact with the deviceWISE (dw) IoT Platform.  The definition of each function is described below along with a few examples demonstrating how to connect and use deviceWISE Cloud.

Connectivity

API Prototype definition
tr50_create int tr50_create(void **tr50, const char *client_id, const char *host, int port);
tr50_start int tr50_start(void *tr50);
tr50_stop int tr50_stop(void *tr50);
tr50_delete int tr50_delete(void *tr50);
tr50_config_set_username int tr50_config_set_username(void *tr50, const char *username);
tr50_config_set_password int tr50_config_set_password(void *tr50, const char *password);
tr50_set_application_token  int tr50_set_application_token (void *tr50, const char *application_token);
tr50_set_thing_key int tr50_set_thing_key(void *tr50, const char *thing_key);
tr50_command_register int tr50_command_register(void *tr50, const char *command, tr50_command_callback callback);
tr50_method_register int tr50_method_register(void *tr50, const char *method, tr50_method_callback callback);

Usage Examples: Connecting to the deviceWISE Cloud.

// Setup the connection to the TR50 server.
ret = tr50_create(tr50, client_id, host, port);
if (ret != 0) {
    printf("tr50_create(): ERROR [%d]\n", ret);
    return 0;
} else {
    printf("tr50_create(): OK\n");
}
if (port == SSL_PORT) {
    tr50_config_set_ssl(*tr50, 1);
}
//Setup authentication
tr50_config_set_username(*tr50, client_id);
tr50_config_set_password(*tr50, app_token);
 
// Connect to the TR50 server.
if (tr50_start(*tr50) != 0) {
    printf("tr50_start(): ERROR [%d]\n", ret);
    return 1;
} else {
    printf("tr50_start(): OK\n");
}

Communication

API Prototype definition
tr50_message_create int tr50_message_create(void **message);
tr50_message_add_command int tr50_message_add_command(void *message, const char *cmd_id, const char *cmd, JSON *params);
tr50_stop int tr50_message_delete(void *message);
tr50_delete int tr50_api_call_sync(void *tr50, void *message, void **reply, int timeout); 
tr50_api_call_async int tr50_api_call_async(void *tr50, void *message, int *seq_id, tr50_async_reply_callback callback, void *custom, int timeout);
tr50_api_raw_async int tr50_api_raw_async(void *tr50, const char *request_json, int *seq_id, tr50_async_raw_reply_callback callback, void *custom, int timeout);
tr50_api_raw_sync int tr50_api_raw_sync(void *tr50, const char *request_json, char **reply_json, int timeout);

Usage Examples: Connecting and communicating with M2M Service.

//create a message handle
if ((ret = tr50_message_create(&message)) != 0) {
    return ret;
}
//build a set of commands to add to message
if ((ret = tr50_message_add_command(message,"1",cmd, params)) != 0) {
    tr50_message_delete(message);
    return ret;
}
//send the message containing the set of commands
if ((ret = tr50_api_call_sync(tr50, message, &reply, 5000)) != 0) {
    tr50_message_delete(message);
    return ret;
}
//retrieve the reply for the first command sent and handle errors
if ((ret = tr50_reply_get_error_code(reply,"1")) != 0) {
    const char *error_message = tr50_reply_get_error_message(reply,"1");
    if((error_message!=NULL)&&(error_msg!=NULL) ){
        *error_msg =(char *)_memory_clone((void*)error_message, strlen(error_message));
    }
    tr50_reply_delete(reply);
    return ret;
}
//extract the params from the reply for the first command sent.
else if (reply_params != NULL)  {
    *reply_params = (JSON*)tr50_reply_get_params(reply,"1",TRUE);
}
if(reply!=NULL) {
    tr50_reply_delete(reply);
}

Response

API Prototype definition
tr50_reply_get_error_code int tr50_reply_get_error_code(void *reply, const char *cmd_id);
tr50_reply_get_error_message const char *tr50_reply_get_error_message(void *reply, const char *cmd_id);
tr50_reply_get_error int tr50_reply_get_error(void *reply, const char *cmd_id, char **error_message);
tr50_reply_get_params JSON *tr50_reply_get_params(void *reply, const char *cmd_id, int detach);
tr50_reply_delete int tr50_reply_delete(void *reply);