Defining Property Callback Functions

ThingWorx Edge C SDK > How to Set Up an Application > Defining Properties > Defining Property Callback Functions

The property callback function is registered to be called when a request for a specific property is received from ThingWorx Platform; for example, if a service or a mashup references a property.

typedef enum msgCodeEnum (*property_cb) (const char * entityName, const char* propertyName,
twInfoTable** value, char isWrite, void * userdata)

The following parameters are passed to this function:

• entityName — the name of the entity this request is for

• propertyName — the name of the property the request is for

• twInfoTable ** value — a pointer to an twInfoTable that will contain the new property value if this is a write or will be populated with the current property value if this is a read. (For information on InfoTables, refer to the section, twInfoTable.)

• isWrite — a Boolean indicator saying whether this is a read or a write

• userdata — any user data value that was passed in when the callback was registered.

The return value of the function should be a message code enumeration as defined in src/api/twDefinitions.h. These message codes reflect the overall success or failure of your read or write operation locally. For more information about the return values, refer to the appendix, Callback Function Return Codes.

Pushing Property Changes from ThingWorx to Edge Devices.

When properly bound to a remote property on an Edge device, properties on ThingWorx RemoteThing instances can be used for both reading values from and writing new values to the device. For C SDK implementations, use the function, twApi_RegisterPropertyCallback(), to register properties for which you expect ThingWorx Platform to push down values. Then use the property handler callbacks to update the property values received from ThingWorx Platform.

When a new value is set for a remote property on a RemoteThing instance, the value is sent down to the edge drive. For Remote Properties configured with a Cache Option of Read from Server Cache, ThingWorx Platform continues to show the old value of the property until the edge device confirms the new value by sending it back in a property update. This behavior gives the device the ability to decide if the new value is valid before updating the value in ThingWorx Platform.

To ensure that a property displays an accurate value at all times, you can set the Cache Option to Fetch from Remote on Every Read. This setting increases the amount of data sent between ThingWorx Platform and the edge device because every request for the property retrieves the data directly from the device. Use this option sparingly with devices on metered connection.

/*****************
Property Handler Callbacks
******************/
enum msgCodeEnum propertyHandler(const char * entityName, const char * propertyName,
twInfoTable ** value, char isWrite, void * userdata) {
TW_LOG(TW_TRACE,"propertyHandler - Function called for Entity %s, Property %s", entityName, propertyName);
if (value) {
if (isWrite && *value) {
/* Property Writes */
if (strcmp(propertyName, "InletValve") == 0)
twInfoTable_GetBoolean(*value, propertyName, 0, &properties.InletValve);FaultStatus);
else if (strcmp(propertyName, "TemperatureLimit") == 0)
twInfoTable_GetNumber(*value, propertyName, 0, &properties.TemperatureLimit);
else return NOT_FOUND;
return SUCCESS;
} else {
/* Property Reads */
if (strcmp(propertyName, "InletValve") == 0)
*value = twInfoTable_CreateFromBoolean(propertyName, properties.InletValve);
else if (strcmp(propertyName, "Temperature") == 0)
*value = twInfoTable_CreateFromNumber(propertyName, properties.Temperature);
else if (strcmp(propertyName, "TemperatureLimit") == 0)
*value = twInfoTable_CreateFromNumber(propertyName, properties.TemperatureLimit);
else if (strcmp(propertyName, "Location") == 0)
*value = twInfoTable_CreateFromLocation(propertyName, &properties.Location);
else if (strcmp(propertyName, "BigGiantString") == 0)
*value = twInfoTable_CreateFromString(propertyName, properties.BigGiantString, TRUE);
else return NOT_FOUND;
}
return SUCCESS;
} else {
TW_LOG(TW_ERROR,"propertyHandler - NULL pointer for value");
return BAD_REQUEST;
}
}