 |
Diffusion C API 6.11.5
|
|
Diffusion C API 6.11.5
|
Allows a client session to receive notifications about changes to selected topics. More...
Data Structures | |
| struct | diffusion_topic_notification_listener_s |
| Structure for adding a topic notification listener. More... | |
Typedefs | |
| typedef int(* | on_listener_registered_cb) (const DIFFUSION_REGISTRATION_T *registration, void *context) |
| Callback when the listener has successfully been registered. | |
| typedef int(* | on_descendant_notification_cb) (const char *topic_path, const DIFFUSION_TOPIC_NOTIFICATION_TYPE_T type, void *context) |
| Notification for an immediate descendant of a selected topic path. | |
| typedef int(* | on_topic_notification_cb) (const char *topic_path, const TOPIC_SPECIFICATION_T *specification, const DIFFUSION_TOPIC_NOTIFICATION_TYPE_T type, void *context) |
| A notification for a selected topic. | |
| typedef void(* | on_topic_notification_listener_close_cb) (void) |
| Callback for when a topic notification listener has been closed. | |
| typedef struct diffusion_topic_notification_listener_s | DIFFUSION_TOPIC_NOTIFICATION_LISTENER_T |
| Structure for adding a topic notification listener. | |
Enumerations | |
| enum | DIFFUSION_TOPIC_NOTIFICATION_TYPE_T { TOPIC_ADDED , TOPIC_SELECTED , TOPIC_REMOVED , TOPIC_DESELECTED } |
Functions | |
| bool | diffusion_topic_notification_add_listener (SESSION_T *session, const DIFFUSION_TOPIC_NOTIFICATION_LISTENER_T listener, DIFFUSION_API_ERROR *api_error) |
| Register a listener to receive topic notifications. | |
Allows a client session to receive notifications about changes to selected topics.
Sessions receive notifications via DIFFUSION_TOPIC_NOTIFICATION_LISTENER_Ts The listener will be provided with the topic specifications for all topics bound to paths that match registered selectors, and any subsequent notifications for the selected topics on those paths, via DIFFUSION_TOPIC_NOTIFICATION_LISTENER_T.on_topic_notification. Notifications will only be emitted for paths where a topic is bound.
For example, with a registered selector "?a//", if a topic is added at path a/b/c/d with no topics bound to paths higher in the hierarchy DIFFUSION_TOPIC_NOTIFICATION_LISTENER_T.on_topic_notification will be called once with a topic path of "a/b/c/d", a notification type of TOPIC_ADDED, and the topic's associated topic specification.
The nature of the notification is provided by theDIFFUSION_TOPIC_NOTIFICATION_TYPE_T enum. TOPIC_ADDED and TOPIC_REMOVED represent structural changes to the topic tree; TOPIC_SELECTED indicates that a pre-existing topic has been selected by a new registered selector, and similarly TOPIC_DESELECTED indicates that a topic is no longer selected because of changes to the set of registered selectors for the listener.
Registered DIFFUSION_TOPIC_NOTIFICATION_LISTENER_Ts will receive notifications for all topics matching registered selections. Selection of topics using topic selector expressions is provided via the DIFFUSION_REGISTRATION_T associated for a specific listener.
A session can request selections at any time, even if the topics do not exist at the server. Selections are stored on the server and any subsequently added topics that match registered selectors will generate notifications.
Listeners will be informed about the presence or absence of unselected immediate descendants via DIFFUSION_TOPIC_NOTIFICATION_LISTENER_T.on_descendant_notification. This allows listeners to determine whether to select deeper topic paths in order to walk the topic tree. An immediate descendant is defined as the first bound topic on any branch below a given topic path.
For example, for topics at "a/b", "a/c", "a/c/d", "a/e/f/g", the immediate descendants of "a" would be "a/b", "a/c", "a/e/f/g".
Immediate descendant notifications provide a DIFFUSION_TOPIC_NOTIFICATION_TYPE_T to indicate the reason for the notification in the same manner as DIFFUSION_TOPIC_NOTIFICATION_LISTENER_T.on_topic_notification
For example, with a registered selector ">a", if a topic is added at path a/b then DIFFUSION_TOPIC_NOTIFICATION_LISTENER_T.on_descendant_notification will be called with a topic path of "a/b" and a notification type of TOPIC_ADDED. If a topic was subsequently added at path a/b/c, no further notifications will be received until diffusion_topic_notification_registration_select was used to select the deeper topic path ">a/b".
A listener will only be notified about topics for which the session has PATH_PERMISSION_SELECT_TOPIC and PATH_PERMISSION_READ_TOPIC permissions. PATH_PERMISSION_SELECT_TOPIC determines which selectors a listener may register; PATH_PERMISSION_READ_TOPIC determines which selected topics the client may receive notifications for.
| typedef int(* on_descendant_notification_cb) (const char *topic_path, const DIFFUSION_TOPIC_NOTIFICATION_TYPE_T type, void *context) |
Notification for an immediate descendant of a selected topic path.
This notifies the presence or absence of a descendant topic that may subsequently be explicitly selected.
| topic_path | The path of the immediate descendant that is not selected. |
| type | The type of notification. |
| context | User supplied context. |
| typedef int(* on_listener_registered_cb) (const DIFFUSION_REGISTRATION_T *registration, void *context) |
Callback when the listener has successfully been registered.
| registration | The registration for topic notifications. |
| context | User supplied context. |
| typedef int(* on_topic_notification_cb) (const char *topic_path, const TOPIC_SPECIFICATION_T *specification, const DIFFUSION_TOPIC_NOTIFICATION_TYPE_T type, void *context) |
A notification for a selected topic.
| topic_path | The path of the topic that this notification is for. |
| specification | The specification of the topic that this notification is for |
| type | The type of notification. |
| context | User supplied context. |
1.9.8