Loading Shape Libraries
You can use a shape library on any platform in either of two ways:
• The Edge Extension library of EdgeThingShapes can be statically linked to your application at compile time.
• The Edge Extension library of EdgeThingShapes can be dynamically linked at runtime by using a shared library (Linux) or a dll (Windows).
The following sections explain these methods of loading shape libraries and more:
Dynamically Loading Edge Extension Libraries
To load a library dynamically at runtime, call:
void * twExt_LoadExtensionLibrary(char *shapeLibraryName);
If the TWXLIB environment variable is not set, the shapeLibraryName must be the complete path to the shared library or dll. If the variable is set, shapeLibraryName can be a partial path that is relative to the path specified in the TWXLIB environment variable. Note that shapeLibraryName should be just the name of the library to load. It should not include the file extension (.so or .dll.
When a shape library is loaded dynamically at runtime, that library must provide a library initialization function. This function must be named with the name of the shared library. For example, the shared library warehouseshapelib.so would require a function declared inside it that looks like this:
void* init_warehouseshapelib()
This function would be called by twExt_LoadShapeLibrary() as part of the dynamic library loading process.
Statically Linked Shape Libraries
When statically linking a shape library, you are responsible for calling the initialization function for the library (init_<libraryname>()). You must also call this initialization function if you are using shapes that are compiled directly into your application.
In general, call the initialization function from within your application's main() function. This call makes the library available for later use by twExt_CreateThingFromTemplate().
Grouping Things Together by "Kind"
Given the name of a Thing (entityName) and the name of a Thing Template, the twExt_DoesThingImplementTemplate() function determines if the specified Thing extends the requested Thing Template. This function returns TRUE if the Thing extends the Thing Template. This function is useful when you want to group Things together by "kind" based on their Thing Template. For example, if you want to group all model devices that are based on a specific Thing Template, use this function. Here is the prototype of this function:
char twExt_DoesThingImplementTemplate(char *entityName, char *templateName);
Adding an EdgeThingShape to an Existing Thing
To add an EdgeThingShape to an existing Thing, use the twExt_AddEdgeThingShape() function. This function supports an optional namespace name that allows an EdgeThingShape to be added to the same Thing more than once. Any properties or services that use a namespace are added in a format like this: Property A in namespace B appears in a Thing as property B_A.
Here is the prototype of this function:
int twExt_AddEdgeThingShape(const char *entityName,
const char *shapeName,
const char *thing_namespace);
Registering an EdgeThingShape
To add an EdgeThingShape to the map of available shapes ("register" it), use the twExt_RegisterShape() function. To make an EdgeThingShape available for use, specify it in the shape library init functions. Here is the prototype for this function:
void twExt_RegisterShape(const char *shapeName,
shapeHandlerFunction shapeConstructorFunction);