Defining Events
Event definitions describe interrupts that ThingWorx Platform users can subscribe to if they want to be notified when something happens.
Events require that a Data Shape for event data be defined in code. Events can be defined in code or by using the following attributes:
• ThingWorxEventDefinition — Defines the event.
• name — Name of the event.
• description — A description for the event.
• dataShape — The name of the Data Shape for the event data.
Events must be registered. Refer to
Register Events for details. The registered event is reported back to the ThingWorx Platform when the platform is browsing. Note that events do not have callbacks since they cannot be invoked from the ThingWorx Platform to the Edge. You can add aspects to an event that is already registered, using
twApi_AddAspectToService.
Unregistering Events
To unregister an event, use the callback function, twApi_UnregisterEventCallback (v.2.2.5 and later of the C SDK). This callback removes an event from the callback list. The event will no longer be reported back to the ThingWorx Platform. When using this callback, specify the following parameters:
|
Name
|
Description
|
|
entityName
|
The name of the entity to which the service belongs.
|
|
eventName
|
The name of the event to be unregistered.
|
|
userdata
|
An opaque pointer that is passed into the callback function.
|
The callback returns #TW_OK if the event is successfully unregistered and a positive integer if an error is encountered. For information about errors, refer to the filetwErrorsh. The signature for this callback is in twApi.h, and its implementation is in twApi.c.
Example 2. Unregistering an Event
Here is an example from a unit test. This test tries to register an event, unregister it, and verify it was unregistered:
TEST(unit_twApi_RegisterEvent, registerEventSuccess) {
callbackInfo *cbInfoQuery=NULL;
void* result;
TEST_ASSERT_EQUAL(TW_OK, twApi_Initialize(TW_HOST, TW_PORT, TW_URI, TW_APP_KEY, NULL, MESSAGE_CHUNK_SIZE, MESSAGE_CHUNK_SIZE, FALSE));
TEST_ASSERT_EQUAL(TW_OK, twApi_RegisterEvent(TW_THING, TEST_ENTITY_NAME, TEST_EVENT_NAME, NULL, NULL));
cbInfoQuery = (callbackInfo *) TW_MALLOC(sizeof(callbackInfo));
cbInfoQuery->characteristicType = TW_EVENTS;
cbInfoQuery->entityName = TEST_ENTITY_NAME;
cbInfoQuery->entityType = TW_THING;
cbInfoQuery->characteristicName = TEST_EVENT_NAME;
// Verify Event was created
TEST_ASSERT_EQUAL(TW_OK,twDict_Find(tw_api->callbackList,cbInfoQuery,&result));
TEST_ASSERT_EQUAL(TW_OK, twApi_UnregisterEventCallback(TEST_ENTITY_NAME, TEST_EVENT_NAME,NULL));
// Verify Event memory was released
TEST_ASSERT_EQUAL(TW_MAP_MISSING,twDict_Find(tw_api->callbackList,cbInfoQuery,&result));
}