ThingWorx C SDK
Classes | Macros | Typedefs | Functions
twShapes.h File Reference

EdgeThingShape and EdgeThingTemplate Support. More...

#include <stdio.h>
#include <string.h>
#include <time.h>
#include "twApi.h"
#include "twOSPort.h"
#include "stringUtils.h"
#include <twBaseTypes.h>
#include "twStandardProps.h"

Go to the source code of this file.

Classes

struct  twThingNameToTemplateRecord
 
struct  twThingNameToShapeRecord
 

Macros

#define true   1
 

Typedefs

typedef void(* shapeHandlerFunction) (const char *, const char *)
 
typedef void(* templateHandlerFunction) (const char *, const char *)
 
typedef twInfoTable *(* InitialConfigurationHandler) (void)
 
typedef void(* OnConfigureHandler) (twInfoTable *, char *)
 
typedef struct twThingNameToTemplateRecord twThingNameToTemplateRecord
 
typedef struct twThingNameToShapeRecord twThingNameToShapeRecord
 

Functions

void * twExt_LoadExtensionLibrary (char *shapeLibraryName)
 
char twExt_DoesThingImplementShape (char *entityName, char *shapeName)
 
char twExt_DoesThingImplementTemplate (char *entityName, char *templateName)
 
int twExt_AddEdgeThingShape (const char *entityName, const char *shapeName, const char *thing_namespace)
 
void twExt_RegisterShape (const char *shapeName, shapeHandlerFunction shapeConstructorFunction)
 
void twExt_RegisterTemplate (const char *templateName, templateHandlerFunction handler)
 
int twExt_CreateThingFromTemplate (const char *thingName, const char *templateName,...)
 
void twExt_SetThingAsBasedOnTemplateOf (const char *thingName, const char *templateName)
 
void twExt_InheritFromTemplate (const char *thingName, const char *templateNameToInherit)
 
service_cb twExt_GetCallbackForService (char *entityName, char *serviceName)
 
int twExt_RegisterStandardProperty (const char *entityName, const char *propertyName, const char *thing_namespace, enum BaseType propertyType, const char *propertyDescription, char *propertyPushType, double propertyPushThreshold)
 
int twExt_RegisterNamespacedService (const char *entityName, const char *serviceName, const char *thing_namespace, const char *serviceDescription, twDataShape *inputs, enum BaseType outputType, twDataShape *outputDataShape, service_cb cb, void *userdata)
 

Detailed Description

EdgeThingShape and EdgeThingTemplate Support.

Author
bill..nosp@m.reic.nosp@m.hardt.nosp@m.@thi.nosp@m.ngwor.nosp@m.x.co.nosp@m.m

Implements the loading of libraries which provide EdgeThingTemplates and EdgeThingShapes for the C SDK.

Function Documentation

int twExt_AddEdgeThingShape ( const char *  entityName,
const char *  shapeName,
const char *  thing_namespace 
)

Add a Shape to an existing Thing. Supports an optional namespace name which will allow a Shape to be added to the same thing more than once. Any properties or services that use a namespace will be added in a format like this: Property A in namespace B would appear in a thing as property B_A.

Parameters
entityNameThe name of the thing to apply this shape to.
shapeNameThe name of the registered shape to apply.
thing_namespaceThe name to use as a namespace prefix.
Returns
Result code.
  • TW_OK indicates shape added to Thing.
  • TW_LIST_ENTRY_NOT_FOUND indicates Shape was not found.
int twExt_CreateThingFromTemplate ( const char *  thingName,
const char *  templateName,
  ... 
)

Creates a new thing from a thingName, templateName and multiple shape names. Count can be zero and is ignored, the list of shapes must be terminated with a NULL parameter.

There is a convenience macro defined, TW_MAKE_THING(), that will add the NULL for you.

Parameters
thingNameThe name of a Thing you would like to create.
templateNameThe registered thing template to base this thing on.
...A NULL terminated list of shape name strings
Returns
TW_OK on success or {TW_ERROR_SHAPE_DOES_NOT_EXIST,TW_ERROR_TEMPLATE_DOES_NOT_EXIST} Note that after templateName you can pass multiple shape names to also add to this thing but this function must have one last argument which is NULL to end the list of shapes. If no shapes are to be used, this function must have a minimum of three arguments, thingName, templateName, and NULL indicating that it has no ThingShapes.
char twExt_DoesThingImplementShape ( char *  entityName,
char *  shapeName 
)

Given the name of a Thing (entityName) and the name of a Shape, returns TRUE if that thing has implemented the provided shape. Can be useful for grouping Things together by "Kind" based on their shape.

Parameters
entityNameThe name of the Thing you wish to test.
shapeNameThe name of the Shape you want to test for.
Returns
Boolean: Shape implemented by Thing.
char twExt_DoesThingImplementTemplate ( char *  entityName,
char *  templateName 
)

Given the name of a Thing (entityName) and the name of a ThingTemplate , returns TRUE if that thing extends the requested ThingTemplate. Can be useful for grouping Things together by "Kind" based on their ThingTemplate.

Parameters
entityNameThe name of the Thing you wish to test.
templateNameThe name of the ThingTemplate you want to test for.
Returns
Boolean: Thing extends ThingTemplate.
service_cb twExt_GetCallbackForService ( char *  entityName,
char *  serviceName 
)

Get the callback function for any service registered on a Thing. This can then be used to call the service locally from your application.

Parameters
entityNameThe name of the Thing which implements this service.
serviceNameThe name of the service who's function you need to look up.
Returns
Callback function which can be used to call this service.
void twExt_InheritFromTemplate ( const char *  thingName,
const char *  templateNameToInherit 
)

Apply the provided thingTemplate to the provided thingName. Used to manage inheritance from another ThingTemplate.

There are convenience marcos defined that wrap this function, TW_DECLARE_TEMPLATE and TW_TEMPLATE, which may be used.

Parameters
thingNameThe name of a Thing you would like to create.
templateNameToInheritThe name of the already registered ThingTemplate you would like to base your Thing on.
void* twExt_LoadExtensionLibrary ( char *  shapeLibraryName)

Dynamically loads a shape library and calls its init_<libraryname>() function to register its Shapes and Templates. shapeLibraryName must be a full path to a library if the TWXLIB environment variable is not set, or a partial path relative to the TWXLIB environment variable if it is set.

Parameters
shapeLibraryNameThe name of the library to load. Should not include the file extension.
Returns
Extension library handle.
int twExt_RegisterNamespacedService ( const char *  entityName,
const char *  serviceName,
const char *  thing_namespace,
const char *  serviceDescription,
twDataShape inputs,
enum BaseType  outputType,
twDataShape outputDataShape,
service_cb  cb,
void *  userdata 
)

Namespaced services are services that have been given a prefix to avoid a runtime name collision. A namespace string is used as a prefix to make this service name unique. Namespaces should only be provided by the developer who is using your Shape or Template to build their own thing.

There are convenience macros defined that wrap this function, TW_DECLARE_SERVICE() and TW_SERVICE(), which may be used.

Parameters
entityNameThe name of the Thing you want to add this property to
serviceNameThe name of the Service you would like to create
thing_namespaceThe namespace to be used when this Service is created. NULL is acceptable if namespace support is not required.
serviceDescriptionA text description of this Service. This is optional and NULL can be used in place of a description.
inputsA Datashape that describes a row of Primitive types which are used to describe the input parameters of this service.
outputTypeA primitive type selected from the BaseType enum value list. This is the expected type used as the return value for this function.
outputDataShapeIf outputType is TW_INFOTABLE then this parameter must be a DataShape describing the columns used in the returned InfoTable of this Service.
cbA service callback function. This function will be called when your service is called from ThingWorx. It must use the format specificed by the service_cb function definition. Ex: myService(const char * entityName, const char * serviceName, twInfoTable * params, twInfoTable ** content, void * userdata);
userdataAny user provided data you would like provided to this function at runtime using the userdata argument of service_cb.
Returns
Result code.
  • TW_OK indicates success.
  • {TW_NULL_OR_INVALID_API_SINGLETON,TW_ERROR_ALLOCATING_MEMORY, TW_INVALID_PARAM, TW_ERROR_ITEM_EXISTS} indicates failure. Keep in mind that this function will fail with TW_ERROR_ITEM_EXISTS is the service name you are trying to use already exists.
void twExt_RegisterShape ( const char *  shapeName,
shapeHandlerFunction  shapeConstructorFunction 
)

Adds a Thing Shape to the Map of available shapes. Should be called in shape library init functions to make a Shape available for use.

Parameters
shapeNameThe name of the shape to register.
shapeConstructorFunctionFunction to build shape.
int twExt_RegisterStandardProperty ( const char *  entityName,
const char *  propertyName,
const char *  thing_namespace,
enum BaseType  propertyType,
const char *  propertyDescription,
char *  propertyPushType,
double  propertyPushThreshold 
)

Namespaced properties are properties that have been given a prefix to avoid a runtime name collision. A namespace string is used as a prefix to make this property name unique. Namespaces should only be provided by the developer who is using your Shape or Template to build their own thing.

There are convenience macros defined that wrap this function, TW_PROPERTY() and TW_PROPERTY_LONG(), which may be used.

Parameters
entityNameThe name of the Thing you want to add this property to.
propertyNameThe name of the property you want to add.
thing_namespaceThe namespace to be used when this property is created. NULL is acceptable if namespace support is not required.
propertyTypeA primitive type selected from the BaseType enum value list.
propertyDescriptionA text description of this property. This is optional and NULL can be used in place of a description.
propertyPushTypeA string constant describing a strategy for how a property should change before it is considered significant. Options are one of the constants {TW_PUSH_TYPE_ALWAYS, TW_PUSH_TYPE_VALUE, TW_PUSH_TYPE_NEVER}.
propertyPushThresholdA numeric value to be used in conjunction with the selected propertyPushType. For example, if TW_PUSH_TYPE_VALUE is chosen, then propertyPushThreshold would be the amount of change required before this property would be considered to have changed.
Returns
Result code.
  • TW_OK indicates success.
  • TW_INVALID_PARAM indicates the property name chosen already exists and cannot be created.
void twExt_RegisterTemplate ( const char *  templateName,
templateHandlerFunction  handler 
)

Called from a shape library initialization function to register an Edge Thing Template for later use.

Parameters
templateNameThe name of the Template to register.
handlerTemplate construction function.
void twExt_SetThingAsBasedOnTemplateOf ( const char *  thingName,
const char *  templateName 
)

Register the Template a Thing is based on.

Parameters
thingNameThe name of a Thing you would like to create.
templateNameThe name of a Thing you would like to create.