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.
|
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 |
|
|
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) |
|
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.
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
-
entityName | The name of the thing to apply this shape to. |
shapeName | The name of the registered shape to apply. |
thing_namespace | The 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
-
thingName | The name of a Thing you would like to create. |
templateName | The 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
-
entityName | The name of the Thing you wish to test. |
shapeName | The 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
-
entityName | The name of the Thing you wish to test. |
templateName | The 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
-
entityName | The name of the Thing which implements this service. |
serviceName | The 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
-
thingName | The name of a Thing you would like to create. |
templateNameToInherit | The 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
-
shapeLibraryName | The 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
-
entityName | The name of the Thing you want to add this property to |
serviceName | The name of the Service you would like to create |
thing_namespace | The namespace to be used when this Service is created. NULL is acceptable if namespace support is not required. |
serviceDescription | A text description of this Service. This is optional and NULL can be used in place of a description. |
inputs | A Datashape that describes a row of Primitive types which are used to describe the input parameters of this service. |
outputType | A primitive type selected from the BaseType enum value list. This is the expected type used as the return value for this function. |
outputDataShape | If outputType is TW_INFOTABLE then this parameter must be a DataShape describing the columns used in the returned InfoTable of this Service. |
cb | A 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); |
userdata | Any 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
-
shapeName | The name of the shape to register. |
shapeConstructorFunction | Function 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
-
entityName | The name of the Thing you want to add this property to. |
propertyName | The name of the property you want to add. |
thing_namespace | The namespace to be used when this property is created. NULL is acceptable if namespace support is not required. |
propertyType | A primitive type selected from the BaseType enum value list. |
propertyDescription | A text description of this property. This is optional and NULL can be used in place of a description. |
propertyPushType | A 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}. |
propertyPushThreshold | A 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
-
templateName | The name of the Template to register. |
handler | Template construction function. |
void twExt_SetThingAsBasedOnTemplateOf |
( |
const char * |
thingName, |
|
|
const char * |
templateName |
|
) |
| |
Register the Template a Thing is based on.
- Parameters
-
thingName | The name of a Thing you would like to create. |
templateName | The name of a Thing you would like to create. |