notify_create and
notify_destroy register callbacks to be
called when the node is created and destroyed, respectively. The
node_id argument specifies for which node the callback should be
installed. By specifying both the node_id and the
recursive arguments it is possible to get notifications for all
nodes in a subtree. It is safe to read the node with get_node in
the osa_node_tree_query interface from within the callback
function.
Calling notify_create without recursive being set is only useful when used together with reverse execution, as only then can the node ID of a node that is to be created later be known.
notify_property_change registers a callback that is triggered when the given property key changes on the node (or any property, if key is nil). The callback function will receive the name of the property that was changed in the key argument and the old and new values of that property in the old_val and new_val arguments.
notify_event register a callback cb to be called when an event occurs for the given node_id. If the event_name argument is nil the callback will be associated with all events, by providing a specific event name instead the callback will only trigger for that particular event type. The event_data argument passed to the callback contains tracker specific data associated with the event. See specific tracker documentation for details.
If recursive, the callback will be triggered for the given node's descendants as well as the node itself.
Most callbacks have cpu and obj arguments. The cpu argument specifies the processor that caused the event, but may be nil if the event was not caused by a processor. The obj will contain the object that implements the interface. The node_id argument passed to the callback specifies the node ID for the node that has been created, destroyed, modified or has triggered an event.
notify_cpu_move_from and notify_cpu_move_to register callbacks that are triggered when a processor moves from one node path to another—but only if either path lies in the subtree rooted at the given node node_id.
Since a single update to the node tree can result in several different callbacks being triggered, reading nodes with get_node from a callback function may yield a result containing updates whose callbacks have not yet been run. For example, if two nodes change their name attributes simultaneously, the final state of both nodes may be visible to both property change callbacks. With notify_callbacks_done, you can register a callback that will run when all other callbacks pertaining to a particular change in the node tree are finished.
notify_enable register a callback cb to be called when the tracker framework is enabled.
notify_disable register a callback cb to be called when the tracker framework is disabled.
The functions that install callbacks return an integer ID. This ID can be passed to cancel_notify in order to uninstall the callback. In case of error in a notification function the returned cancel ID from that function will be 0.
New callbacks registered inside a registered callback will not be called until the next transaction they trigger for. Canceled callbacks are canceled immediately.
SIM_INTERFACE(osa_node_tree_notification)
{
cancel_id_t (*notify_create)(conf_object_t *NOTNULL obj,
node_id_t node_id, bool recursive,
void (*cb)(cbdata_call_t data,
conf_object_t *obj,
conf_object_t *cpu,
node_id_t node_id),
cbdata_register_t data);
cancel_id_t (*notify_destroy)(conf_object_t *NOTNULL obj,
node_id_t node_id, bool recursive,
void (*cb)(cbdata_call_t data,
conf_object_t *obj,
conf_object_t *cpu,
node_id_t node_id),
cbdata_register_t data);
cancel_id_t (*notify_property_change)(
conf_object_t *NOTNULL obj, node_id_t node_id,
const char *key, bool recursive,
void (*cb)(cbdata_call_t data, conf_object_t *obj,
conf_object_t *cpu, node_id_t node_id,
const char *key, attr_value_t old_val,
attr_value_t new_val),
cbdata_register_t data);
cancel_id_t (*notify_cpu_move_from)(
conf_object_t *NOTNULL obj, node_id_t node_id,
void (*cb)(cbdata_call_t data, conf_object_t *obj,
conf_object_t *cpu, attr_value_t node_path),
cbdata_register_t data);
cancel_id_t (*notify_cpu_move_to)(
conf_object_t *NOTNULL obj, node_id_t node_id,
void (*cb)(cbdata_call_t data, conf_object_t *obj,
conf_object_t *cpu, attr_value_t node_path),
cbdata_register_t data);
cancel_id_t (*notify_event)(
conf_object_t *NOTNULL obj, node_id_t node_id,
const char *event_name, bool recursive,
void (*cb)(cbdata_call_t data, conf_object_t *obj,
conf_object_t *cpu, node_id_t node_id,
const char *event_name, attr_value_t event_data),
cbdata_register_t data);
cancel_id_t (*notify_enable)(
conf_object_t *NOTNULL obj,
void (*cb)(cbdata_call_t data, conf_object_t *obj),
cbdata_register_t data);
cancel_id_t (*notify_disable)(
conf_object_t *NOTNULL obj,
void (*cb)(cbdata_call_t data, conf_object_t *obj),
cbdata_register_t data);
void (*cancel_notify)(conf_object_t *NOTNULL obj,
cancel_id_t cancel_id);
cancel_id_t (*notify_callbacks_done)(
conf_object_t *NOTNULL obj, uint64 node_id,
void (*cb)(cbdata_call_t data, conf_object_t *obj),
cbdata_register_t data);
};
#define OSA_NODE_TREE_NOTIFICATION_INTERFACE "osa_node_tree_notification"