SDK Reference Part 8

[#1]

• Step 10: C - Info Tables
• Step 11: C - Events
• Step 12: C - Services

Step 10: C - Info Tables

Infotables are used for storing and retrieving data from service calls. An infotable has a DataShapeDefinition that describes the names, base types, and additional information about each field within the table.

In order to create an Infotable, you can do so with the provided macros or functions.

 

Define With Macros

In order to define Infotables using a macro, use TW_MAKE_INFOTABLE or TW_MAKE_IT. Both macros can be used interchangeably.

NOTE: The macros are all defined in the twMacros.h header file.

twInfoTable* it;
it = TW_MAKE_IT(
    TW_MAKE_DATASHAPE(DATSHAPE_NAME_SENSOR_READINGS,
            TW_DS_ENTRY("ActivationTime", TW_NO_DESCRIPTION ,TW_DATETIME),
            TW_DS_ENTRY("SensorName", TW_NO_DESCRIPTION ,TW_NUMBER),
            TW_DS_ENTRY("Temperature", TW_NO_DESCRIPTION ,TW_NUMBER),
            TW_DS_ENTRY("Pressure", TW_NO_DESCRIPTION ,TW_NUMBER),
            TW_DS_ENTRY("FaultStatus", TW_NO_DESCRIPTION ,TW_BOOLEAN),
            TW_DS_ENTRY("InletValve", TW_NO_DESCRIPTION ,TW_BOOLEAN),
            TW_DS_ENTRY("TemperatureLimit", TW_NO_DESCRIPTION ,TW_NUMBER),
            TW_DS_ENTRY("TotalFlow", TW_NO_DESCRIPTION ,TW_INTEGER)
    ),
    TW_IT_ROW(TW_MAKE_DATETIME_NOW,TW_MAKE_STRING("Sensor Alpha"),TW_MAKE_NUMBER(60),TW_MAKE_NUMBER(25),TW_MAKE_BOOL(TRUE),TW_MAKE_BOOL(TRUE),TW_MAKE_NUMBER(150),TW_MAKE_NUMBER(77)),
    TW_IT_ROW(TW_MAKE_DATETIME_NOW,TW_MAKE_STRING("Sensor Beta"),TW_MAKE_EMPTY,TW_MAKE_NUMBER(35),TW_MAKE_BOOL(FALSE),TW_MAKE_BOOL(TRUE),TW_MAKE_EMPTY,TW_MAKE_NUMBER(88)),
    TW_IT_ROW(TW_MAKE_DATETIME_NOW,TW_MAKE_STRING("Sensor Gamma"),TW_MAKE_EMPTY,TW_MAKE_NUMBER(80),TW_MAKE_BOOL(TRUE),TW_MAKE_BOOL(FALSE),TW_MAKE_NUMBER(150),TW_MAKE_NUMBER(99))
);

 

Define Without Macros

In order to define Infotables without using a macro, use the twDataShape_CreateFromEntries function.

twInfoTable * it = NULL;
twInfoTableRow * row = NULL;

it = twInfoTable_Create(ds); 
if (!it) {
    TW_LOG(TW_ERROR,"createNewThing: Error creating infotable");
    twDataShape_Delete(ds);
    return TW_ERROR_ALLOCATING_MEMORY;
}

row = twInfoTableRow_Create(twPrimitive_CreateFromString("SimpleThing_2", TRUE));
if (!row) {
    TW_LOG(TW_ERROR,"createNewThing: Error creating infotable row");
    twInfoTable_Delete(it);
    return TW_ERROR_ALLOCATING_MEMORY;
}

twInfoTableRow_AddEntry(row, twPrimitive_CreateFromString("A new Thing", TRUE));
twInfoTableRow_AddEntry(row, twPrimitive_CreateFromString("RemoteThing", TRUE));

twInfoTable_AddRow(it, row);

 

Retrieve With Macros

Many of the calls to services in ThingWorx will return an InfoTable of information. Below is an example of using the TW_GET_NUMBER_PARAM macro to retrieve values from an Infotable:

///Data is stored in the params variable
///Retrieve the a and b values then store them in variables

twInfoTable * params
double a, b;

TW_GET_NUMBER_PARAM(params, "a", 0, &a);
TW_GET_NUMBER_PARAM(params, "b", 0, &b);

 

Retrieve Without Macros

Below is an example of using the twInfoTable_GetNumber function to retrieve values from an Infotable:

///Data is stored in the params variable
///Retrieve the a and b values then store them in variables

twInfoTable * params
double a, b;

twInfoTable_GetNumber(params, "a", 0, &a);
twInfoTable_GetNumber(params, "b", 0, &b);

Step 11: C - Events

Event definitions describe interrupts that ThingWorx can subscribe to in order to receive notifications when something happens.

The parameters for an event definition are:

• name
• description
• dataShape
• aspects

In order to create an Event, you can do so with the provided macros or functions.

 

Define With Macros

In order to define an Event using a macro, you will use TW_DECLARE_EVENT or TW_EVENT. Both macros can be used interchangeably.

NOTE: The macros are all defined in the twMacros.h header file.

TW_EVENT("SteamSensorFault",
    "Steam sensor event",
         TW_MAKE_DATASHAPE(
             "SteamSensorFault",
             TW_DS_ENTRY("message",TW_NO_DESCRIPTION,TW_STRING)
        )
);

 

Define Without Macros

In order to define an Event without using a macro, you will use the twApi_RegisterEvent function. See an example below of how to utilize the twApi_RegisterEvent function and adding a row of data:

twApi_RegisterEvent(TW_THING, "SteamSensor", "SteamSensorFault", "Steam sensor event", ds);

 

Fire With Macros

In order to fire an Event using a macro, you will use TW_FIRE_EVENT.

NOTE: The macros are all defined in the twMacros.h header file.

TW_FIRE_EVENT(thingName, "SteamSensorFault",
  TW_MAKE_IT(TW_MAKE_DATASHAPE(
          "SteamSensorFault",
          TW_DS_ENTRY("message", TW_NO_DESCRIPTION, TW_STRING)
             ), TW_IT_ROW(TW_MAKE_STRING(msg))
  ));

 

Fire Without Macros

In order to fire an Event without using a macro, you will use the twApi_FireEvent function. See an example below of how to utilize the twApi_FireEvent function and adding a row of data:

twApi_FireEvent(TW_THING, "SteamSensor", "SteamSensorFault", eventInfoTable, -1, TRUE)

Step 12: C - Services

Service Handler Callbacks

The service callback function is registered to be called when a request for a specific service is received from the ThingWorx Platform. These functions must have the same signature as shown here:

typedef enum msgCodeEnum (*service_cb) (const char * entityName, const char * serviceName,  twInfoTable * params,twInfoTable ** content, void * userdata)

Below is an example of a single service that adds two numbers that can be registered with and without macros:

/*****************
Service Callbacks
******************/
/* Example of handling a single service in a callback */
enum msgCodeEnum addNumbersService(const char * entityName, const char * serviceName, twInfoTable * params, twInfoTable ** content, void * userdata) {
        double a, b, res;
        TW_LOG(TW_TRACE,"addNumbersService - Function called");
        if (!params || !content) {
                TW_LOG(TW_ERROR,"addNumbersService -                   NULL params or content pointer");
                return BAD_REQUEST;
        }

        twInfoTable_GetNumber(params, "a", 0, &a);
        twInfoTable_GetNumber(params, "b", 0, &b);
        res = a + b;
        *content = twInfoTable_CreateFromNumber("result", res);
        if (*content) return SUCCESS;
        else return INTERNAL_SERVER_ERROR;
}

NOTE: The return value of the function is TWX_SUCCESS if the request completes successfully or an appropriate error code if not (should be a message code enumeration as defined in twDefinitions.h).

 

Register Service Callback

In order to register a service handler callback using macros, utilize TW_DECLARE_SERVICE as shown below:

TW_MAKE_THING(thingName,TW_THING_TEMPLATE_GENERIC);
    TW_DECLARE_SERVICE( "AddNumbers",
        "Add two numbers together",
        TW_MAKE_DATASHAPE(NO_SHAPE_NAME,
        TW_DS_ENTRY("a", TW_NO_DESCRIPTION ,TW_NUMBER),
        TW_DS_ENTRY("b", TW_NO_DESCRIPTION ,TW_NUMBER)),
        TW_NUMBER,
        TW_NO_RETURN_DATASHAPE,
        addNumbersService
    );

Click here to view Part 9 of this guide