Object synchronization API

Collaboration diagram for Object synchronization API:

Modules
	Object synchronization API
	Parameter synchronization API
	synchronization API types
	synchronization API Utility functions

Functions
amxs_status_t	amxs_sync_ctx_new (amxs_sync_ctx_t **ctx, const char *object_a, const char *object_b, int attributes)
	Synchronization context constructor function. More...
void	amxs_sync_ctx_delete (amxs_sync_ctx_t **ctx)
	Synchronization context destructor function. More...
amxs_status_t	amxs_sync_ctx_init (amxs_sync_ctx_t *ctx, const char *object_a, const char *object_b, int attributes)
	Synchronization context initialization function. More...
void	amxs_sync_ctx_clean (amxs_sync_ctx_t *ctx)
	Synchronization context cleanup function. More...
amxs_status_t	amxs_sync_ctx_copy (amxs_sync_ctx_t **dest, amxs_sync_ctx_t *src, void *priv)
	Copies an existing synchronization context to a new synchronization context. More...
amxs_status_t	amxs_sync_ctx_start_sync (amxs_sync_ctx_t *ctx)
	Starts the object synchronization. More...
void	amxs_sync_ctx_stop_sync (amxs_sync_ctx_t *ctx)
	Stops the object synchronization. More...
static bool	amxs_sync_ctx_is_started (const amxs_sync_ctx_t *const ctx)
	Checks is the synchronization context is running. More...
amxs_status_t	amxs_sync_ctx_set_paths (amxs_sync_ctx_t *const ctx, const char *object_a, const char *object_b)
	Updates the object paths of the synchronization context. More...
amxs_status_t	amxs_sync_ctx_add_param (amxs_sync_ctx_t *ctx, amxs_sync_param_t *param)
	Adds a synchronization parameter to a synchronization context. More...
amxs_status_t	amxs_sync_ctx_add_new_param (amxs_sync_ctx_t *ctx, const char *param_a, const char *param_b, int attributes, amxs_translation_cb_t translation_cb, amxs_action_cb_t action_cb, void *priv)
	Creates and adds a synchronization parameter to a synchronization context. More...
amxs_status_t	amxs_sync_ctx_add_new_copy_param (amxs_sync_ctx_t *ctx, const char *param_a, const char *param_b, int attributes)
	Creates and adds a synchronization parameter to a synchronization context. More...
amxs_status_t	amxs_sync_ctx_add_object (amxs_sync_ctx_t *ctx, amxs_sync_object_t *object)
	Adds a synchronization object to a synchronization context. More...
amxs_status_t	amxs_sync_ctx_add_new_object (amxs_sync_ctx_t *ctx, const char *object_a, const char *object_b, int attributes, amxs_translation_cb_t translation_cb, amxs_action_cb_t action_cb, void *priv)
	Creates and adds a synchronization object to a synchronization context. More...

Detailed Description

Function Documentation

amxs_sync_ctx_add_new_copy_param()

amxs_status_t amxs_sync_ctx_add_new_copy_param	(	amxs_sync_ctx_t *	ctx,
		const char *	param_a,
		const char *	param_b,
		int	attributes
	)

Creates and adds a synchronization parameter to a synchronization context.

Allocates memory for a new synchronization parameter and initializes this parameter. Then adds it to the synchronization context.

Adding the synchronization parameter fails when:

• The parameter was already added to the context
• The parameter attributes are conflicting with those of the context. E.g. The context has the AMXS_SYNC_ONLY_B_TO_A attribute set, and the parameter has AMXS_SYNC_ONLY_A_TO_B set.

If the context attributes are more strict than those of the parameter, the parameter attributes will be updated to match those of the context.

Uses default translation amxs_sync_batch_param_copy_trans_cb and action amxs_sync_param_copy_action_cb callbacks.

Parameters

ctx	Pointer to a synchronization context.
param_a	Name of the parameter in object A
param_b	Name of the parameter in object B
attributes	Bitwise OR of zero or more of the following attributes: AMXS_SYNC_DEFAULT AMXS_SYNC_ONLY_B_TO_A AMXS_SYNC_ONLY_A_TO_B AMXS_SYNC_INIT_B

Returns

• amxs_status_ok: the new synchronization parameter is added to the synchronization context
• amxs_status_duplicate: another synchronization parameter with the same direction and parameter names already exists for this synchronization context
• amxs_status_invalid_attr: the attributes of the synchronization parameter are conflicting with those of the synchronization context
• amxs_status_unknown_error: any other error

Definition at line 903 of file amxs_sync_ctx.c.

                                                               {
    return amxs_sync_ctx_add_new_param(ctx,
                                       param_a,
                                       param_b,
                                       attributes | AMXS_SYNC_PARAM_BATCH,
                                       NULL,
                                       NULL,
                                       NULL);
}

amxs_sync_ctx_add_new_object()

amxs_status_t amxs_sync_ctx_add_new_object	(	amxs_sync_ctx_t *	ctx,
		const char *	object_a,
		const char *	object_b,
		int	attributes,
		amxs_translation_cb_t	translation_cb,
		amxs_action_cb_t	action_cb,
		void *	priv
	)

Creates and adds a synchronization object to a synchronization context.

Allocates memory for a new synchronization object and initializes this object. Then adds it to the synchronization context.

Adding the synchronization object fails when:

• The object was already added to the context
• The object attributes are conflicting with those of the context. E.g. The context has the AMXS_SYNC_ONLY_B_TO_A attribute set, and the object has AMXS_SYNC_ONLY_A_TO_B set.

If the context attributes are more strict than those of the object, the object attributes will be updated to match those of the context.

Parameters

ctx	Pointer to a synchronization context.
object_a	Name of the object in object A
object_b	Name of the object in object B
attributes	Bitwise OR of zero or more of the following attributes: AMXS_SYNC_DEFAULT AMXS_SYNC_ONLY_B_TO_A AMXS_SYNC_ONLY_A_TO_B AMXS_SYNC_INIT_B
translation_cb	Callback function to translate data coming from an object event. The output data of this function will be passed to the action callback function if this function executes succesfully. If this argument is NULL, the data from the event will be passed directly to the action callback function.
action_cb	Callback function to act on an object event.
priv	Pointer to user data which will be passed to the translation and action callbacks.

Returns

• amxs_status_ok: the new synchronization object is added to the synchronization context
• amxs_status_duplicate: another synchronization object with the same direction and object names already exists for this synchronization context
• amxs_status_invalid_attr: the attributes of the synchronization object are conflicting with those of the synchronization context
• amxs_status_unknown_error: any other error

Definition at line 929 of file amxs_sync_ctx.c.

                                                       {
    amxs_status_t status = amxs_status_unknown_error;
    amxs_sync_object_t* object = NULL;
 
    status = amxs_sync_object_new(&object, object_a, object_b, attributes, translation_cb, action_cb, priv);
    when_failed(status, exit);
 
    status = amxs_sync_ctx_add_object(ctx, object);
    if(status != amxs_status_ok) {
        amxs_sync_object_delete(&object);
    }
 
exit:
    return status;
}

amxs_sync_ctx_add_new_param()

amxs_status_t amxs_sync_ctx_add_new_param	(	amxs_sync_ctx_t *	ctx,
		const char *	param_a,
		const char *	param_b,
		int	attributes,
		amxs_translation_cb_t	translation_cb,
		amxs_action_cb_t	action_cb,
		void *	priv
	)

Creates and adds a synchronization parameter to a synchronization context.

Allocates memory for a new synchronization parameter and initializes this parameter. Then adds it to the synchronization context.

Adding the synchronization parameter fails when:

• The parameter was already added to the context
• The parameter attributes are conflicting with those of the context. E.g. The context has the AMXS_SYNC_ONLY_B_TO_A attribute set, and the parameter has AMXS_SYNC_ONLY_A_TO_B set.

If the context attributes are more strict than those of the parameter, the parameter attributes will be updated to match those of the context.

Parameters

ctx	Pointer to a synchronization context.
param_a	Name of the parameter in object A
param_b	Name of the parameter in object B
attributes	Bitwise OR of zero or more of the following attributes: AMXS_SYNC_DEFAULT AMXS_SYNC_ONLY_B_TO_A AMXS_SYNC_ONLY_A_TO_B AMXS_SYNC_INIT_B
translation_cb	Callback function to translate data coming from a parameter changed event. The output data of this function will be passed to the action callback function if this function executes succesfully. If this argument is NULL, the data from the event will be passed directly to the action callback function.
action_cb	Callback function to act on a parameter changed event.
priv	Pointer to user data which will be passed to the translation and action callbacks.

Returns

• amxs_status_ok: the new synchronization parameter is added to the synchronization context
• amxs_status_duplicate: another synchronization parameter with the same direction and parameter names already exists for this synchronization context
• amxs_status_invalid_attr: the attributes of the synchronization parameter are conflicting with those of the synchronization context
• amxs_status_unknown_error: any other error

Definition at line 881 of file amxs_sync_ctx.c.

                                                      {
    amxs_status_t status = amxs_status_unknown_error;
    amxs_sync_param_t* param = NULL;
 
    status = amxs_sync_param_new(&param, param_a, param_b, attributes, translation_cb, action_cb, priv);
    when_failed(status, exit);
 
    status = amxs_sync_ctx_add_param(ctx, param);
    if(status != amxs_status_ok) {
        amxs_sync_param_delete(&param);
    }
 
exit:
    return status;
}

amxs_sync_ctx_add_object()

amxs_status_t amxs_sync_ctx_add_object	(	amxs_sync_ctx_t *	ctx,
		amxs_sync_object_t *	object
	)

Adds a synchronization object to a synchronization context.

The synchronization object can be be created using amxs_sync_object_new.

Adding the synchronization object fails when:

• The object was already added to the context
• The object attributes are conflicting with those of the context. E.g. The context has the AMXS_SYNC_ONLY_B_TO_A attribute set, and the object has AMXS_SYNC_ONLY_A_TO_B set.

If the context attributes are more strict than those of the object, the object attributes will be updated to match those of the context.

Parameters

ctx	Pointer to a synchronization context.
object	Pointer to a synchronization object.

Returns

• amxs_status_ok: the synchronization object is added to the synchronization context
• amxs_status_duplicate: another synchronization object with the same direction and object names already exists for this synchronization context
• amxs_status_invalid_attr: the attributes of the synchronization object are conflicting with those of the synchronization context
• amxs_status_unknown_error: any other error

Definition at line 916 of file amxs_sync_ctx.c.

                                                                                         {
    amxs_status_t status = amxs_status_unknown_error;
    when_null(ctx, exit);
    when_null(object, exit);
    when_false_status(ctx->type == amxs_sync_type_ctx, exit, status = amxs_status_invalid_type);
    when_false_status(object->type == amxs_sync_type_object, exit, status = amxs_status_invalid_type);
 
    status = amxs_sync_entry_add_entry(ctx, object);
 
exit:
    return status;
}

amxs_sync_ctx_add_param()

amxs_status_t amxs_sync_ctx_add_param	(	amxs_sync_ctx_t *	ctx,
		amxs_sync_param_t *	param
	)

Adds a synchronization parameter to a synchronization context.

The synchronization parameter can be be created using amxs_sync_param_new.

Adding the synchronization parameter fails when:

• The parameter was already added to the context
• The parameter attributes are conflicting with those of the context. E.g. The context has the AMXS_SYNC_ONLY_B_TO_A attribute set, and the parameter has AMXS_SYNC_ONLY_A_TO_B set.

If the context attributes are more strict than those of the parameter, the parameter attributes will be updated to match those of the context.

Parameters

ctx	Pointer to a synchronization context.
param	Pointer to a synchronization parameter.

Returns

• amxs_status_ok: the synchronization parameter is added to the synchronization context
• amxs_status_duplicate: another synchronization parameter with the same direction and parameter names already exists for this synchronization context
• amxs_status_invalid_attr: the attributes of the synchronization parameter are conflicting with those of the synchronization context
• amxs_status_unknown_error: any other error

Definition at line 868 of file amxs_sync_ctx.c.

                                                                                      {
    amxs_status_t status = amxs_status_unknown_error;
    when_null(ctx, exit);
    when_null(param, exit);
    when_false_status(ctx->type == amxs_sync_type_ctx, exit, status = amxs_status_invalid_type);
    when_false_status(param->type == amxs_sync_type_param, exit, status = amxs_status_invalid_type);
 
    status = amxs_sync_entry_add_entry(ctx, param);
 
exit:
    return status;
}

amxs_sync_ctx_clean()

void amxs_sync_ctx_clean

(

amxs_sync_ctx_t *

ctx

)

Synchronization context cleanup function.

Frees any memory that was allocated to store data in this synchronization context.

If the synchronization context has any synchronization objects or parameters attached to it, these will be removed and freed.

Parameters

ctx	Pointer to a synchronization context.

Definition at line 752 of file amxs_sync_ctx.c.

                                               {
    when_null(ctx, exit);
    when_false(ctx->type == amxs_sync_type_ctx, exit);
 
    amxs_sync_entry_clean(ctx);
 
exit:
    return;
}

amxs_sync_ctx_copy()

amxs_status_t amxs_sync_ctx_copy	(	amxs_sync_ctx_t **	dest,
		amxs_sync_ctx_t *	src,
		void *	priv
	)

Copies an existing synchronization context to a new synchronization context.

When the copy is successful the synchronization object paths must be updated using amxs_sync_ctx_set_paths before starting the synchronization context

Parameters

dest	Pointer to a synchronization context pointer, will contain the copy.
src	The synchronization context that will be copied.
priv	Private data.

Returns

amxs_status_ok when the synchronization context is created, or another status code when failed to create the synchronization context.

Definition at line 762 of file amxs_sync_ctx.c.

                                                                                           {
    return amxs_sync_entry_copy(dest, src, priv);
}

amxs_sync_ctx_delete()

void amxs_sync_ctx_delete

(

amxs_sync_ctx_t **

ctx

)

Synchronization context destructor function.

Frees all memory allocated for a synchronization context.

If the synchronization context has any synchronization objects or parameters attached to it, these will be removed and freed as well.

Parameters

ctx	Pointer to a synchronization context pointer.

Definition at line 727 of file amxs_sync_ctx.c.

                                                 {
    when_null(ctx, exit);
    when_null(*ctx, exit);
    when_false((*ctx)->type == amxs_sync_type_ctx, exit);
 
    amxs_sync_entry_delete(ctx);
 
exit:
    return;
}

amxs_sync_ctx_init()

amxs_status_t amxs_sync_ctx_init	(	amxs_sync_ctx_t *	ctx,
		const char *	object_a,
		const char *	object_b,
		int	attributes
	)

Synchronization context initialization function.

Initializes a synchronization context that was allocated on the stack.

Allocates memory for a new synchronization context and initializes this context.

Use amxs_sync_ctx_clean to make sure that all allocated memory to store the data is freed.

Please note that the attributes that are set on the synchronization context will always override those that are set on syncronization objects or parameters. E.g. when setting the AMXS_SYNC_ONLY_B_TO_A attribute on the context, and setting AMXS_SYNC_DEFAULT on a parameter, the syncronyzation will only be executed from object B to object A.

Parameters

ctx	Pointer to a synchronization context.
object_a	Path to the first object to be synchronized, hereafter referenced as object A.
object_b	Path to the second object to be synchronized, hereafter referenced as object B.
attributes	Bitwise OR of zero or more of the following attributes: AMXS_SYNC_DEFAULT AMXS_SYNC_ONLY_B_TO_A AMXS_SYNC_ONLY_A_TO_B AMXS_SYNC_INIT_B

Returns

amxs_status_ok when the synchronization context is initialized, or another status code when failed to initialize the synchronization context.

Definition at line 738 of file amxs_sync_ctx.c.

                                                 {
    return amxs_sync_entry_init(ctx,
                                object_a,
                                object_b,
                                attributes,
                                NULL,
                                NULL,
                                amxs_sync_type_ctx,
                                NULL);
}

amxs_sync_ctx_is_started()

static bool amxs_sync_ctx_is_started ( const amxs_sync_ctx_t *const  ctx )

inlinestatic

Checks is the synchronization context is running.

Checks if the synchronization context was already startued

Parameters

ctx	Pointer to a synchronization context.

Returns

• true: when started
• false: when not started yet.

Definition at line 231 of file amxs_sync_ctx.h.

                                                                {
    return ctx == NULL? false:!amxc_llist_is_empty(&ctx->subscriptions);
}

amxs_sync_ctx_new()

amxs_status_t amxs_sync_ctx_new	(	amxs_sync_ctx_t **	ctx,
		const char *	object_a,
		const char *	object_b,
		int	attributes
	)

Synchronization context constructor function.

Allocates memory for a new synchronization context and initializes the context.

Use amxs_sync_ctx_delete to remove the synchronizaion context and free all allocated memory.

The object paths that can be used in a synchronization context must be an absolute path to:

• singleton objects
• instance objects

Search paths (key addressing) can be used but must resolve to exatly one object. Key paths can be used as well, but are not recomended.

Creating a synchronization context using template objects paths (ending with a multi-instance object) are not allowed, in this case creation will fail.

Parameters

ctx	Pointer to a synchronization context pointer. The address of the new allocated synchronization context is stored in this pointer.
object_a	Path to the first object to be synchronized, hereafter referenced as object A.
object_b	Path to the second object to be synchronized, hereafter referenced as object B.
attributes	Bitwise OR of zero or more of the following attributes: AMXS_SYNC_DEFAULT AMXS_SYNC_ONLY_B_TO_A AMXS_SYNC_ONLY_A_TO_B AMXS_SYNC_INIT_B

Returns

amxs_status_ok when the synchronization context is created, or another status code when failed to create the synchronization context.

Definition at line 713 of file amxs_sync_ctx.c.

                                                {
    return amxs_sync_entry_new(ctx,
                               object_a,
                               object_b,
                               attributes,
                               NULL,
                               NULL,
                               amxs_sync_type_ctx,
                               NULL);
}

amxs_sync_ctx_set_paths()

amxs_status_t amxs_sync_ctx_set_paths	(	amxs_sync_ctx_t *const	ctx,
		const char *	object_a,
		const char *	object_b
	)

Updates the object paths of the synchronization context.

When a copy is made of a synchronization context using amxs_sync_ctx_copy, the object paths of the new synchronization context can be set using this function.

The new set object paths must match the original object paths at supported data model level.

Parameters

ctx	Pointer to a synchronization context.
object_a	The new path to object a.
object_b	The new path to object b.

Returns

• amxs_status_ok: the new paths are set.
• amxs_status_invalid_arg: an invalid path has been provided.
• amxs_status_object_not_found: object A or object B was not found.
• amxs_status_unknown_error: any other error

Definition at line 828 of file amxs_sync_ctx.c.

                                                            {
    amxs_status_t status = amxs_status_unknown_error;
    char* supported_a = NULL;
    char* supported_b = NULL;
 
    when_null(ctx, exit);
    when_str_empty_status(object_a, exit, status = amxs_status_invalid_arg);
    when_str_empty_status(object_b, exit, status = amxs_status_invalid_arg);
 
    supported_a = ctx->a;
    supported_b = ctx->b;
 
    ctx->a = strdup(object_a);
    ctx->b = strdup(object_b);
 
    if(ctx->bus_ctx_a == NULL) {
        ctx->bus_ctx_a = amxb_be_who_has(ctx->a);
    }
    if(ctx->bus_ctx_b == NULL) {
        ctx->bus_ctx_b = amxb_be_who_has(ctx->b);
    }
 
    when_failed_status(amxs_sync_ctx_validate_path(ctx, amxs_sync_a_to_b), exit,
                       status = amxs_status_object_not_found);
    when_failed_status(amxs_sync_ctx_validate_path(ctx, amxs_sync_b_to_a), exit,
                       status = amxs_status_object_not_found);
 
    when_false_status(amxs_sync_ctx_paths_match(ctx->a, supported_a), exit, status = amxs_status_invalid_arg);
    when_false_status(amxs_sync_ctx_paths_match(ctx->b, supported_b), exit, status = amxs_status_invalid_arg);
 
    status = amxs_status_ok;
 
exit:
    free(supported_a);
    free(supported_b);
    return status;
}

amxs_sync_ctx_start_sync()

amxs_status_t amxs_sync_ctx_start_sync

(

amxs_sync_ctx_t *

ctx

)

Starts the object synchronization.

Starts the synchronization by looking up the initial values and then subscribing for changes on the configured objects and parameters. Synchronization will fail if no objects or parameters are attached to the context.

Parameters

ctx	Pointer to a synchronization context.

Returns

amxs_status_ok when the synchronization is started succesfully, or another status code when failed to start the synchronization.

Definition at line 766 of file amxs_sync_ctx.c.

                                                             {
    amxs_status_t status = amxs_status_unknown_error;
    when_null(ctx, exit);
 
    when_false_status(ctx->type == amxs_sync_type_ctx, exit, status = amxs_status_invalid_type);
    when_true_status(amxc_llist_is_empty(&ctx->entries), exit, status = amxs_status_empty_context);
 
    if(ctx->bus_ctx_a == NULL) {
        ctx->bus_ctx_a = amxb_be_who_has(ctx->a);
    }
    if(ctx->bus_ctx_b == NULL) {
        ctx->bus_ctx_b = amxb_be_who_has(ctx->b);
    }
 
    if((ctx->attributes & AMXS_SYNC_ONLY_B_TO_A) == 0) {
        when_null_status(ctx->bus_ctx_a, exit, status = amxs_status_object_not_found);
        when_failed_status(amxs_sync_ctx_validate_path(ctx, amxs_sync_a_to_b), exit,
                           status = amxs_status_object_not_found);
        when_failed_status(amxs_sync_ctx_verify_local_dm(ctx, amxs_sync_b_to_a), exit,
                           status = amxs_status_object_not_found);
    }
 
    if((ctx->attributes & AMXS_SYNC_ONLY_A_TO_B) == 0) {
        when_null_status(ctx->bus_ctx_b, exit, status = amxs_status_object_not_found);
        when_failed_status(amxs_sync_ctx_validate_path(ctx, amxs_sync_b_to_a), exit,
                           status = amxs_status_object_not_found);
        when_failed_status(amxs_sync_ctx_verify_local_dm(ctx, amxs_sync_a_to_b), exit,
                           status = amxs_status_object_not_found);
    }
 
    if((ctx->attributes & AMXS_SYNC_ONLY_B_TO_A) == 0) {
        status = amxs_subscribe(ctx, ctx, amxs_sync_a_to_b);
        when_failed(status, cleanup_subs);
    }
 
    if((ctx->attributes & AMXS_SYNC_ONLY_A_TO_B) == 0) {
        status = amxs_subscribe(ctx, ctx, amxs_sync_b_to_a);
        when_failed(status, cleanup_subs);
    }
 
    status = amxs_do_initial_sync(ctx);
    when_failed(status, cleanup_subs);
 
cleanup_subs:
    if(status != amxs_status_ok) {
        amxc_llist_clean(&ctx->subscriptions, amxs_llist_it_delete_subscription);
    }
 
exit:
    return status;
}

amxs_sync_ctx_stop_sync()

void amxs_sync_ctx_stop_sync

(

amxs_sync_ctx_t *

ctx

)

Stops the object synchronization.

Stops the synchronization by unsubscribing for changes on the configured objects and parameters.

Parameters

ctx	Pointer to a synchronization context.

Definition at line 818 of file amxs_sync_ctx.c.

                                                   {
    when_null(ctx, exit);
    when_false(ctx->type == amxs_sync_type_ctx, exit);
 
    amxc_llist_clean(&ctx->subscriptions, amxs_llist_it_delete_subscription);
 
exit:
    return;
}