Data Model Eventing

Functions
int	amxb_subscribe (amxb_bus_ctx_t *const ctx, const char *object, const char *expression, amxp_slot_fn_t slot_cb, void *priv)
	Subscribes for events of a object tree. More...
int	amxb_unsubscribe (amxb_bus_ctx_t *const ctx, const char *object, amxp_slot_fn_t slot_cb, void *priv)
	Removes an event subscription. More...
int	amxb_publish (amxb_bus_ctx_t *const ctx, const char *object, const char *name, amxc_var_t *data)
	Publish an event for a specific object. More...
int	amxb_subscription_new (amxb_subscription_t **subscription, amxb_bus_ctx_t *bus_ctx, const char *object, const char *expression, amxp_slot_fn_t slot_cb, void *priv)
	Creates a subscription object and subscribes for events of a object tree. More...
int	amxb_subscription_delete (amxb_subscription_t **subscription)
	Deletes a subscription object and unsubscribe for events of a object tree. More...
amxb_subscription_t *	amxb_subscription_find (amxb_bus_ctx_t *bus_ctx, const char *object, amxp_slot_fn_t slot_cb, void *priv)
	Find an exact subscription. More...
amxb_subscription_t *	amxb_subscription_find_parent (amxb_bus_ctx_t *bus_ctx, const char *object)
	Find a parent subscription. More...
amxb_subscription_t *	amxb_subscription_find_child (amxb_bus_ctx_t *bus_ctx, const char *object)
	Find a child subscription. More...
int	amxb_wait_for_object (const char *object)
	Checks if an object is available, if not waits for it. More...

Detailed Description

Function Documentation

amxb_publish()

int amxb_publish	(	amxb_bus_ctx_t *const	ctx,
		const char *	object,
		const char *	name,
		amxc_var_t *	data
	)

Publish an event for a specific object.

This function can only be used when a data model was registered to the provided bus context using amxb_register.

Any event can be published for any object on the condition that the event was added to the data model signal manager.

Parameters

ctx	The bus context (or connection)
object	object path to the object object paths must end with a "."
name	event name
data	event data

Returns

AMXB_STATUS_OK remote function has completed successful

Definition at line 347 of file amxb_ba_subscribe.c.

                                   {
    int retval = -1;
    amxd_object_t* obj = NULL;
 
    when_null(ctx, exit);
    when_null(ctx->dm, exit);
    when_null(ctx->bus_ctx, exit);
    when_str_empty(object, exit);
    when_str_empty(name, exit);
 
    obj = amxd_object_findf(amxd_dm_get_root(ctx->dm), "%s", object);
 
    if(obj != NULL) {
        amxd_object_emit_signal(obj, name, data);
        retval = amxd_status_ok;
    } else {
        retval = amxd_status_object_not_found;
    }
 
exit:
    return retval;
}

amxb_subscribe()

int amxb_subscribe	(	amxb_bus_ctx_t *const	ctx,
		const char *	object,
		const char *	expression,
		amxp_slot_fn_t	slot_cb,
		void *	priv
	)

Subscribes for events of a object tree.

Subscribes for all events matching the given filter on an object (sub)tree.

Using the provided object path, all events matching the given expression, of that object or any of the child objects (instances included) are passed to the callback function.

The subscription can be removed using amxb_unsubscribe.

Parameters

ctx	The bus context (or connection)
object	object path to the object object paths must end with a "."
expression	an expression used to filter the events
slot_cb	callback function, called for each matching event
priv	private data, passed to the callback function

Returns

AMXB_STATUS_OK remote function has completed successful

Definition at line 205 of file amxb_ba_subscribe.c.

                               {
    int retval = -1;
    char* obj_path = NULL;
    amxc_var_t info;
    amxd_path_t path;
    amxb_request_t* req = NULL;
    amxc_string_t rel_path;
    amxc_string_t str_expr;
 
    amxd_path_init(&path, NULL);
    amxc_var_init(&info);
    amxc_string_init(&rel_path, 64);
    amxc_string_init(&str_expr, 0);
 
    when_null(ctx, exit);
    when_null(ctx->bus_ctx, exit);
    when_null(object, exit);
    when_null(slot_cb, exit);
 
    amxd_path_setf(&path, true, "%s", object);
    if((path.type == amxd_path_invalid) ||
       (path.type == amxd_path_reference) ||
       (path.type == amxd_path_supported)) {
        goto exit;
    }
    obj_path = amxd_path_get_fixed_part(&path, false);
 
    retval = amxb_describe(ctx, obj_path, 0, &info, 5);
    if(retval == 0) {
        free(obj_path);
        amxb_build_path(&info, &path);
        obj_path = amxd_path_get_fixed_part(&path, false);
    }
 
    when_null(obj_path, exit);
 
    amxc_var_set_type(&info, AMXC_VAR_ID_HTABLE);
    amxc_var_add_key(cstring_t, &info, "expression", expression);
    req = amxb_async_call(ctx, obj_path, "_subscribe", &info, NULL, NULL);
    amxb_close_request(&req);
 
    if(*obj_path != 0) {
        obj_path[strlen(obj_path) - 1] = 0;
    }
 
    retval = amxb_build_expression(&str_expr, &path, expression);
    when_failed(retval, exit);
    expression = amxc_string_get(&str_expr, 0);
 
    if(ctx->dm != NULL) {
        retval = amxb_subscribe_local_impl(ctx, obj_path, expression, slot_cb, priv);
        when_true(retval == 0, exit);
    }
 
    retval = amxb_subscribe_be_impl(ctx, obj_path, expression, slot_cb, priv);
 
exit:
    amxc_string_clean(&str_expr);
    amxc_string_clean(&rel_path);
    amxd_path_clean(&path);
    amxc_var_clean(&info);
    free(obj_path);
    return retval;
}

amxb_subscription_delete()

int amxb_subscription_delete

(

amxb_subscription_t **

subscription

)

Deletes a subscription object and unsubscribe for events of a object tree.

Unsubscribes for events of an object (sub)tree.

The passes subscription object must be created with amxb_subscription_new

Parameters

subscription

The subscription object

Returns

AMXB_STATUS_OK when subscription object was deleted and unsubscribe for events was successful. If unsubscribing for events fail, the subscription object will be deleted

Definition at line 250 of file amxb_subscription.c.

                                                                 {
    int rv = AMXB_STATUS_OK;
    amxb_sub_t* sub = NULL;
 
    when_null(subscription, exit);
    when_null(*subscription, exit);
 
    sub = amxc_container_of((*subscription), amxb_sub_t, data);
    rv = amxb_subscription_remove((*subscription));
 
    amxc_llist_it_take(&(*subscription)->it);
    free((*subscription)->object);
    free(sub);
 
    *subscription = NULL;
 
exit:
    return rv;
}

amxb_subscription_find()

amxb_subscription_t* amxb_subscription_find	(	amxb_bus_ctx_t *	bus_ctx,
		const char *	object,
		amxp_slot_fn_t	slot_cb,
		void *	priv
	)

Find an exact subscription.

Searches in the given bus context for the first matching subscription. A subscription is matching when the object path, the slot_cb and private data is exactly matching .

Parameters

bus_ctx	The bus context (or connection)
object	object or search path, object paths must end with a "."
slot_cb	callback function, called for each matching event
priv	private data, passed to the callback function

Returns

subscription pointer or NULL if no matching found.

Definition at line 216 of file amxb_subscription.c.

                                                        {
    amxb_subscription_t* subscription = NULL;
 
    when_str_empty(object, exit);
    when_null(slot_cb, exit);
 
    amxc_llist_iterate(it, (&bus_ctx->client_subs)) {
        amxb_sub_t* sub = amxc_container_of(it, amxb_sub_t, it);
        subscription = &sub->data;
        if((strcmp(subscription->object, object) == 0) &&
           ( subscription->slot_cb == slot_cb) &&
           ( subscription->priv == priv)) {
            break;
        }
        subscription = NULL;
    }
 
exit:
    return subscription;
}

amxb_subscription_find_child()

amxb_subscription_t* amxb_subscription_find_child	(	amxb_bus_ctx_t *	bus_ctx,
		const char *	object
	)

Find a child subscription.

A child subscription is a subscription taken on a child object path.

If a search path is given only the fixed part of the path is taken into account.

Parameters

bus_ctx	The bus context (or connection)
object	object or search path, object paths must end with a "."

Returns

subscription pointer or NULL if no matching found.

Definition at line 245 of file amxb_subscription.c.

                                                                      {
    return amxb_subscription_find_relation(bus_ctx, object, false);
}

amxb_subscription_find_parent()

amxb_subscription_t* amxb_subscription_find_parent	(	amxb_bus_ctx_t *	bus_ctx,
		const char *	object
	)

Find a parent subscription.

A parent subscription is a subscription taken on a parent object path.

If a search path is given only the fixed part of the path is taken into account.

Parameters

bus_ctx	The bus context (or connection)
object	object or search path, object paths must end with a "."

Returns

subscription pointer or NULL if no matching found.

Definition at line 240 of file amxb_subscription.c.

                                                                       {
    return amxb_subscription_find_relation(bus_ctx, object, true);
}

amxb_subscription_new()

int amxb_subscription_new	(	amxb_subscription_t **	subscription,
		amxb_bus_ctx_t *	bus_ctx,
		const char *	object,
		const char *	expression,
		amxp_slot_fn_t	slot_cb,
		void *	priv
	)

Creates a subscription object and subscribes for events of a object tree.

Subscribes for all events matching the given filter on an object (sub)tree.

Using the provided object path, all events matching the given expression, of that object or any of the child objects (instances included) are passed to the callback function.

A subscription object amxb_subscription_t is allocated and must be freed using using amxb_subscription_delete.

The allocated subscription object can be stored in a amxc linked list.

Parameters

subscription	The new allocated subscription object
bus_ctx	The bus context (or connection)
object	object or search path, object paths must end with a "."
expression	an expression used to filter the events
slot_cb	callback function, called for each matching event
priv	private data, passed to the callback function

Returns

AMXB_STATUS_OK when subscription object was created and subscribing for events was successful. When failed any other error code can be returned and the subscription object is NULL.

Definition at line 187 of file amxb_subscription.c.

                                      {
    int retval = AMXB_ERROR_UNKNOWN;
    amxb_sub_t* sub = amxb_sub_alloc(object, slot_cb, priv);
 
    when_null(sub, exit);
    *subscription = &sub->data;
 
    retval = amxb_subscribe(bus_ctx,
                            object,
                            expression,
                            (*subscription)->slot_cb,
                            (*subscription)->priv);
    when_failed(retval, exit);
    amxc_llist_append(&bus_ctx->client_subs, &sub->it);
 
exit:
    if((retval != AMXB_STATUS_OK) && (sub != NULL)) {
        free((*subscription)->object);
        free(sub);
        *subscription = NULL;
    }
    return retval;
}

amxb_unsubscribe()

int amxb_unsubscribe	(	amxb_bus_ctx_t *const	ctx,
		const char *	object,
		amxp_slot_fn_t	slot_cb,
		void *	priv
	)

Removes an event subscription.

When not interested any more in events of a certain object (sub)tree, the subscription can be removed using this function.

To remove a subscription the given object path, callback function and private data pointer must match the one used when the subscription was taken with amxb_subscribe.

Parameters

ctx	The bus context (or connection)
object	object path to the object object paths must end with a "."
slot_cb	callback function, called for each matching event
priv	private data, passed to the callback function

Returns

AMXB_STATUS_OK remote function has completed successful

Definition at line 274 of file amxb_ba_subscribe.c.

                                 {
    int retval = -1;
    const amxb_be_funcs_t* fns = NULL;
    amxb_request_t* req = NULL;
    amxp_signal_t* signal = NULL;
    char* obj_path = NULL;
    amxc_var_t info;
    amxd_path_t path;
 
    amxd_path_init(&path, NULL);
    amxc_var_init(&info);
 
    when_null(ctx, exit);
    when_null(ctx->bus_ctx, exit);
    when_str_empty(object, exit);
 
    amxd_path_setf(&path, true, "%s", object);
    if((path.type == amxd_path_invalid) ||
       (path.type == amxd_path_reference) ||
       (path.type == amxd_path_supported)) {
        goto exit;
    }
    obj_path = amxd_path_get_fixed_part(&path, false);
 
    retval = amxb_describe(ctx, obj_path, 0, &info, 5);
    if(retval == 0) {
        free(obj_path);
        amxb_build_path(&info, &path);
        obj_path = amxd_path_get_fixed_part(&path, false);
    }
 
    when_null(obj_path, exit);
 
    amxc_var_set_type(&info, AMXC_VAR_ID_HTABLE);
    req = amxb_async_call(ctx, obj_path, "_unsubscribe", &info, NULL, NULL);
    amxb_close_request(&req);
 
    if(*obj_path != 0) {
        obj_path[strlen(obj_path) - 1] = 0;
    }
 
    retval = -1;
    signal = amxp_sigmngr_find_signal(&ctx->sigmngr, obj_path);
    when_null(signal, exit);
 
    if(priv == NULL) {
        amxp_slot_disconnect(&ctx->sigmngr, obj_path, slot_cb);
    } else {
        amxp_slot_disconnect_signal_with_priv(&ctx->sigmngr, obj_path, slot_cb, priv);
    }
    retval = 0;
    when_true(amxp_signal_has_slots(signal), exit);
 
    fns = ctx->bus_fn;
    if(amxb_is_valid_be_func(fns, unsubscribe, fns->unsubscribe)) {
        retval = fns->unsubscribe(ctx->bus_ctx,
                                  obj_path);
    } else {
        retval = AMXB_STATUS_OK;
    }
 
    amxp_signal_delete(&signal);
 
exit:
    free(obj_path);
    amxd_path_clean(&path);
    amxc_var_clean(&info);
    return retval;
}

amxb_wait_for_object()

int amxb_wait_for_object

(

const char *

object

)

Checks if an object is available, if not waits for it.

When all objects are available, the signal "wait:done" is emitted on the global signal manager.

The signal is not defined by default, and must be added to the global signal manager before calling this method. It is also recommended to connect the callback functions (slots) to the signal prior to calling this method.

This function can be called multiple times. If the function is called multiple times before giving back control to the eventloop, the signal "wait:done" is emitted as soon as all objects are available.

Each time the function is called to wait for a new object, a new signal "wait:<OBJECT-PATH>" is created. This signal will be emitted when this object becomes available. However, as this signal does not exist until the moment the function is called, you cannot connect a slot to it beforehand. You can however use amxp_slot_connect_filtered to filter for the specific signal.

It is possible to add new objects to the waiting list. If "wait:done" signal was already emitted a new wait cycle is started.

The wait for object work asynchronously, so it is possible to start other tasks.

Warning

This function works on all open connections on the moment the function is called. The wait for object feature depends on the bus specific implementation. If the used underlying bus system does not support a wait for feature, it is possible that the signal is never emitted.

Parameters

object

object path

Returns

AMXB_STATUS_OK when successful

Definition at line 105 of file amxb_ba_wait_for.c.

                                             {
    int retval = -1;
    amxd_path_t path;
    char* object_path = NULL;
    amxb_bus_ctx_t* bus_ctx = NULL;
    amxc_string_t signal_name;
    amxp_signal_t* signal = NULL;
 
    amxd_path_init(&path, NULL);
    amxc_string_init(&signal_name, 0);
 
    when_str_empty(object, exit);
 
    amxd_path_setf(&path, true, "%s", object);
    object_path = amxd_path_get_fixed_part(&path, AMXD_OBJECT_TERMINATE);
    amxc_string_setf(&signal_name, "wait:%s", object_path);
 
    signal = amxp_sigmngr_find_signal(NULL, amxc_string_get(&signal_name, 0));
    if(signal == NULL) {
        retval = amxp_signal_new(NULL, &signal, amxc_string_get(&signal_name, 0));
        when_failed(retval, exit);
        amxp_slot_connect(NULL, amxc_string_get(&signal_name, 0), NULL,
                          amxb_wait_object_available, NULL);
        wait_for_objects++;
    }
 
    // When waiting for an object, make sure that the exact full path is matched
    // remove entry from the cache and check again with full path matching
    // full path is the fixed part (no wildcard or search parts)
    amxb_be_cache_remove_path(object_path);
    bus_ctx = amxb_be_who_has_impl(object_path, true);
    if(bus_ctx != NULL) {
        amxp_signal_emit(signal, NULL);
        retval = 0;
    } else {
        retval = amxb_be_for_all_connections(amxb_wait_for_impl, NULL, (void*) object_path);
    }
 
exit:
    free(object_path);
    amxc_string_clean(&signal_name);
    amxd_path_clean(&path);
    return retval;
}