Defining Service Callback Functions
Service callbacks are the functions that are called when a request comes from ThingWorx platform to execute a service on a particular entity. These functions have the following signature:
typedef enum msgCodeEnum (*service_cb) (
const char * entityName,
const char * serviceName,
twInfoTable * params,
twInfoTable ** content);
const char * entityName,
const char * serviceName,
twInfoTable * params,
twInfoTable ** content);
The following table defines the parameters:
|
Parameter
|
Type
|
Description
|
|---|---|---|
|
entityName
|
Input
|
Pointer to a character array. The name is represented as a modified UTF-8 string with the name of the entity targeted in this request. This parameter is guaranteed not to be NULL.
|
|
serviceName
|
Input
|
Pointer to a character array. This is the name of the service to be executed, represented in modified UTF-8. This parameter is guaranteed not to be NULL.
|
|
params
|
Input
|
Pointer to a twInfoTable. This is a pointer to an infotable that contains all of the parameters specified for this invocation of the service. This pointer may be NULL if the service in question has no input parameters. The API owns this pointer and will manage any memory associated with it.
|
|
content
|
Output
|
Pointer to a pointer to a twInfoTable. This is used to return any data the service returns back to the server. The callback function should create a twInfoTable as described previously and pass a pointer to that structure to *content. If the service does not return any data it is OK to set *content to NULL. The API will assume ownership of the pointer in *value, so the callback function does not need to worry about memory management of any infotables passed in or created and returned as values.
|
|
userdata
|
Input
|
The same pointer value that was passed in when this property was registered. This pointer can be used for anything, a typical use is to specify the ‘this’ pointer when using C++ class wrappers.
|
The return value of the callback is an indicator of the success or failure of the service call. You are free to choose any of the return codes defined in the msgCodeEnum enumeration type, defined in src/api/twDefinitions.h, starting with SUCCESS or any applicable larger value. Here is an example of a service handler callback:
How To Handle a Service in a Callback
The service callback function is registered to be called when a request for a specific service is received from ThingWorx Platform.
typedef enum msgCodeEnum (*service_cb) (const char * entityName, const char * serviceName, twInfoTable * params,twInfoTable** content, void * userdata)
The following parameters are passed to this callback function:
• entityName — the name of the entity this request is for (Thing, Resource, for example). Guaranteed to not be NULL.
• serviceName — the name of the service being requested
• twInfoTable *params — a pointer to an twInfoTable that contains all the parameters for the service. May be NULL if service has no parameters. (For information on InfoTables, refer to the section, twInfoTable )
• twInfoTable ** content — a pointer to a pointer to a twInfoTable. content is guaranteed to not be NULL. *content is not.
 |
A new instance of a twInfoTable should be created on the heap and a pointer to it returned.
|
• userdata — any user data value that was passed in when the callback was registered.
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).
Example 1. Service Callback Example
Here is an example of handling a single service in a callback:
/*****************
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;
}
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;
}