Group-based Poll (C API)

With 25.04 a new poll function ziAPIPollDataWithGroup was introduced to the C API. It replaces the old poll function ziAPIPollDataEx. The new function has two major differences from the old one:

1. Instead of expecting a preallocated ZIEvent, ziAPIPollDataWithGroup allocates the memory for the event internally. This means that the user does not have to preallocate memory for the event upfront.
2. It allows independent subscription groups. Nodes can be subscribed to one or multiple groups and each group can be polled independently. This allows a more fine grained control over the data flow. This feature is not available for HF2, MF and UHF devices.

If you don't need different subscription groups, you can use the ZI_DEFAULT_SUBSCRIPTION_GROUP. This is a group that is always available by default.

Warning

HF2, MF and UHF devices do not support subscription groups. For these devices only the ZI_DEFAULT_SUBSCRIPTION_GROUP can be used.

The old poll related functions (ziAPIPollDataEx, ziAPISubscribeEx, ziAPIUnSubscribeEx) are still available. They are equivalent to call ziAPIPollDataWithGroup and ziAPISubscribeWithGroup using ZI_DEFAULT_SUBSCRIPTION_GROUP as group id.

Important

While ziAPIPollDataEx is deprecated, we do not plan its removal. It is recommended to use the new group-based poll functions for new code, but there is no need to migrate existing code.

Migrating without using Custom Groups

For simple use cases where the user does not want to use custom groups the migration only requires rethinking the lifetime of the ZIEvent object. Instead of preallocating and potentially reusing the ZIEvent object the user can now rely on the internal allocation.

Old code that uses ziAPIPollDataEx

ziAPISubscribeEx(conn, path);
ZIEvent* event = ziAPIAllocateEventEx();
ziAPIPollDataEx(conn, event, 1000);
...
ziAPIDeallocateEventEx(event);
ziAPIUnSubscribe(conn, path);

Replacement with ziAPIPollDataWithGroup

ziAPISubscribeEx(conn, path);
ZIEvent* event;
ziAPIPollDataWithGroup(conn, ZI_DEFAULT_SUBSCRIPTION_GROUP, *event, 1000);
...
ziAPIDeallocateEventEx(event);
ziAPIUnSubscribe(conn, path);

Migrating with Custom Groups

For more complex use cases where the user wants to use custom groups the migration requires more effort but also allows more fine grained control over the data flow.

Creating and destroying subscription groups comes at a low cost. Having a subscription group for every node or node type is therefore a good habit.

Old code that uses ziAPIPollDataEx

ziAPISubscribeEx(conn, path1);
ziAPISubscribeEx(conn, path2);
ZIEvent* event = ziAPIAllocateEventEx();
ziAPIPollDataEx(conn, event, 1000);
// Note that this part is highly simplified. Since all updates are reported through
// the same poll. Getting the right amount of samples for every subscribed path
// requires customized logic.
std::string nodePathStr(reinterpret_cast<const char*>(event->path));
if(nodePathStr == path1)
{
  ...
}
elif(nodePathStr == path2)
{
  ...
}
ziAPIDeallocateEventEx(event);
ziAPIUnSubscribe(conn, path1);
ziAPIUnSubscribe(conn, path2);

Replacement with ziAPIPollDataWithGroup

ZISubscriptionGroupId group1;
ziAPICreateSubscriptionGroup(conn, &group1);
ziAPISubscribeWithGroup(conn, group1, path1);

ZISubscriptionGroupId group2;
ziAPICreateSubscriptionGroup(conn, &group2);
ziAPISubscribeWithGroup(conn, group2, path2);

// Handle events for group1/path1
{
  ZIEvent* event;
  ziAPIPollDataWithGroup(conn, group1, &event, 1000);
  // The event contains only data for path1
  ...
  ziAPIDeallocateEventEx(event);
}
// Handle events for group2/path2
{
  ZIEvent* event;
  ziAPIPollDataWithGroup(conn, group2, &event, 1000);
  // The event contains only data for path2
  ...
  ziAPIDeallocateEventEx(event);
}
ziAPIDeleteSubscriptionGroup(conn, group1);
ziAPIDeleteSubscriptionGroup(conn, group2);