RPC Methods

Collaboration diagram for RPC Methods:

Functions
amxd_status_t	amxd_object_add_function (amxd_object_t *const object, amxd_function_t *const func)
	Adds an RPC method definition to the object definition. More...
amxd_status_t	amxd_object_change_function (amxd_object_t *const object, const char *name, amxd_object_fn_t impl)
	Changes the implementation of an object's RPC method. More...
amxd_function_t *	amxd_object_get_function (const amxd_object_t *const object, const char *name)
	Get the definition of a RPC method from an object. More...
amxd_status_t	amxd_object_list_functions (amxd_object_t *const object, amxc_var_t *const list, amxd_dm_access_t access)
	Builds a linked list variant containing all function names available in the object. More...
amxd_status_t	amxd_object_describe_functions (amxd_object_t *const object, amxc_var_t *const value, amxd_dm_access_t access)
	Fetches the full object RPC method definitions in a variant. More...
amxd_status_t	amxd_object_invoke_function (amxd_object_t *const object, const char *func_name, amxc_var_t *const args, amxc_var_t *const ret)
	Calls an object RPC method. More...
uint32_t	amxd_object_get_function_count (amxd_object_t *const object, amxd_dm_access_t access)
	Retruns the number of RPC methods available in an object. More...

Detailed Description

Function Documentation

amxd_object_add_function()

amxd_status_t amxd_object_add_function	(	amxd_object_t *const	object,
		amxd_function_t *const	func
	)

Adds an RPC method definition to the object definition.

After defining a RPC method using amxd_function_new, the function can be added to an object.

All derived objects will inherit the method. It is possible to change the implementation on derived objects using amxd_object_change_function.

RPC methods added to template objects (multi-instance) objects will be available on all instances, if the attribute amxd_fattr_instance (default) is set in the RPC method definition. If the attribute amxd_fattr_template is set the RPC method can be called on the template object.

Parameters

object	the object where the function must be added.
func	the name of the RPC method

Returns

amxd_status_ok when the function is added to the object definition, or another status when an error has occurred.

Definition at line 140 of file amxd_object_function.c.

                                                                    {
    amxd_status_t retval = amxd_status_unknown_error;
    amxd_function_t* object_func = NULL;
    when_null(object, exit);
    when_null(func, exit);
    when_not_null(func->it.llist, exit);
    when_true(amxd_object_is_attr_set(object, amxd_oattr_locked), exit);
 
    amxc_llist_for_each(it, (&object->functions)) {
        const char* object_func_name = NULL;
        const char* func_name = NULL;
        object_func = amxc_llist_it_get_data(it, amxd_function_t, it);
        object_func_name = amxd_function_get_name(object_func);
        func_name = amxd_function_get_name(func);
        if(strcmp(func_name, object_func_name) == 0) {
            break;
        }
        object_func = NULL;
    }
 
    if(object_func == NULL) {
        // functions added to template object by default only work on
        // instances. This is a design descision.
        // For other behavior set the attributes before adding the function
        // to the object
        if(amxd_object_get_type(object) == amxd_object_template) {
            if((func->attr.instance == 0) &&
               ( func->attr.templ == 0)) {
                func->attr.instance = 1;
            }
        }
        amxc_llist_append(&object->functions, &func->it);
        retval = amxd_status_ok;
    } else {
        retval = amxd_status_duplicate;
    }
 
exit:
    return retval;
}

amxd_object_change_function()

amxd_status_t amxd_object_change_function	(	amxd_object_t *const	object,
		const char *	name,
		amxd_object_fn_t	impl
	)

Changes the implementation of an object's RPC method.

Using this function it is possible to change the implementation of a RPC method in an object.

If the implementation is changed for a certain object which has derived objects, the implementation is changed for all these derived objects as well. When changing the implementation of a derived object (like an instance object), the implementation is only changed for this object (or any object derived from that object).

Parameters

object	the object pointer
name	the name of the RPC method
impl	function pointer to the new implementation

Returns

amxd_status_ok when the function implementation is set, or another status when an error has occurred.

Definition at line 182 of file amxd_object_function.c.

                                                                 {
    amxd_status_t retval = amxd_status_unknown_error;
    amxd_function_t* func = NULL;
    amxd_object_t* owner = NULL;
 
    when_null(object, exit);
    when_str_empty(name, exit);
 
    func = amxd_object_get_function(object, name);
    when_null(func, exit);
    owner = amxd_function_get_owner(func);
    if(owner == object) {
        func->impl = impl;
        retval = amxd_status_ok;
    } else {
        amxd_function_t* new_func = NULL;
        retval = amxd_function_copy(&new_func, func);
        when_true(retval != amxd_status_ok, exit);
        new_func->impl = impl;
        when_failed(amxc_llist_append(&object->functions, &new_func->it), exit);
    }
 
exit:
    return retval;
}

amxd_object_describe_functions()

amxd_status_t amxd_object_describe_functions	(	amxd_object_t *const	object,
		amxc_var_t *const	value,
		amxd_dm_access_t	access
	)

Fetches the full object RPC method definitions in a variant.

It can be very handy to get the full definitions of the object RPC methods.

This function is mainly intended for introspection.

Parameters

object	the object pointer
value	variant where the RPC method defintions can be stored
access	must be one of amxd_dm_access_t

Returns

amxd_status_ok when the function implementation is set, or another status when an error has occurred.

Definition at line 420 of file amxd_action_object_describe.c.

                                                                      {
    return amxd_object_describe_item(object,
                                     value,
                                     AMXD_OBJECT_FUNC,
                                     access,
                                     "functions");
}

amxd_object_get_function()

amxd_function_t* amxd_object_get_function	(	const amxd_object_t *const	object,
		const char *	name
	)

Get the definition of a RPC method from an object.

Returns the RPC method definition, if found, with the given name.

When using a derived object, it is possible that the RPC method definition is not owned by the object, use amxd_function_get_owner to get a pointer to the data model object that owns the RPC method definition.

The returned RPC method can be removed from the object using amxd_function_delete. If the object has derived objects, the method is also removed from the derrived objects, unless it was overriden in the derived object using amxd_object_change_function

Parameters

object	the object pointer
name	the name of the RPC method

Returns

returns the function definition if found, NULL otherwise

Definition at line 210 of file amxd_object_function.c.

                                                            {
    amxd_function_t* func = NULL;
    amxc_string_t normalized;
 
    amxc_string_init(&normalized, 0);
 
    when_null(object, exit);
    when_str_empty(name, exit);
 
    amxc_string_setf(&normalized, "%s", name);
    amxc_string_trimr(&normalized, is_brace);
 
    func = amxd_object_get_self_func(object, amxc_string_get(&normalized, 0));
 
    when_not_null(func, exit);
 
    if(amxd_object_get_type(object) == amxd_object_instance) {
        func = amxd_object_get_function(amxd_object_get_parent(object), amxc_string_get(&normalized, 0));
    } else {
        if(amxc_llist_it_is_in_list(&object->derived_from)) {
            amxd_object_t* super = NULL;
            super = amxc_container_of(object->derived_from.llist,
                                      amxd_object_t,
                                      derived_objects);
            func = amxd_object_get_function(super, amxc_string_get(&normalized, 0));
        }
    }
 
exit:
    amxc_string_clean(&normalized);
 
    return func;
}

amxd_object_get_function_count()

uint32_t amxd_object_get_function_count	(	amxd_object_t *const	object,
		amxd_dm_access_t	access
	)

Retruns the number of RPC methods available in an object.

Parameters

object	the object pointer
access	must be one of amxd_dm_access_t

Returns

amxd_status_ok when the function implementation is set, or another status when an error has occurred.

Definition at line 276 of file amxd_object_function.c.

                                                                 {
    uint32_t count = 0;
    amxc_var_t funcs;
    const amxc_llist_t* funcs_list = NULL;
 
    when_null(object, exit);
 
    amxc_var_init(&funcs);
    amxd_object_list_functions(object, &funcs, access);
    funcs_list = amxc_var_constcast(amxc_llist_t, &funcs);
    count = amxc_llist_size(funcs_list);
    amxc_var_clean(&funcs);
 
exit:
    return count;
}

amxd_object_invoke_function()

amxd_status_t amxd_object_invoke_function	(	amxd_object_t *const	object,
		const char *	func_name,
		amxc_var_t *const	args,
		amxc_var_t *const	ret
	)

Calls an object RPC method.

Using this function a RPC method of an object in the local data model can be called (that is an object in the data model of the process you are running in).

To call a function of a remote data model (data model in another process), use the amxb (BAAPI) function amxb_invoke.

When status amxd_status_deferred is returned, the ret will contain the call id and the real return value and status will be returned later. Use amxd_function_set_deferred_cb to register a callback function.

Parameters

object	the object pointer
func_name	name of the function
args	a hash table variant containing the function arguments
ret	a variant pointer where the return value can be stored

Returns

amxd_status_ok when the function implementation is set, or another status when an error has occurred.

Definition at line 245 of file amxd_object_function.c.

                                                                 {
    amxd_status_t retval = amxd_status_unknown_error;
    amxd_function_t* func = NULL;
 
    when_null(ret, exit);
    retval = amxd_object_invoke_check(object, &func, func_name, args);
    when_failed(retval, exit);
 
    retval = func->impl(object, func, args, ret);
    amxd_function_remove_in_args(func, args);
 
    if(retval == amxd_status_deferred) {
        amxd_dm_t* dm = amxd_object_get_dm(object);
        uint64_t call_id = amxc_var_constcast(uint64_t, ret);
        amxd_deferred_ctx_t* call_ctx = amxd_find_deferred(call_id);
        if(call_ctx == NULL) {
            retval = amxd_status_unknown_error;
            amxc_var_clean(ret);
            goto exit;
        }
 
        amxc_llist_append(&dm->deferred, &call_ctx->dm_it);
    }
 
exit:
    return retval;
}

amxd_object_list_functions()

amxd_status_t amxd_object_list_functions	(	amxd_object_t *const	object,
		amxc_var_t *const	list,
		amxd_dm_access_t	access
	)

Builds a linked list variant containing all function names available in the object.

Initializes the variant to amxc_llist_t type and adds all function names available in the object.

The list also includes the functions of the objects from which this object is derived.

It is possible to filter the functions on access. Access token can be one of

• amxd_dm_access_public
• amxd_dm_access_protected (includes public)
• amxd_dm_access_private (includes protected and public)

Parameters

object	the object pointer
list	an initialized variant, will be filled with the RPC method names
access	filter functions at a certain access level

Returns

amxd_status_ok when the function implementation is set, or another status when an error has occurred.

Definition at line 363 of file amxd_action_object_list.c.

                                                                  {
    return amxd_object_list_item(object,
                                 list,
                                 AMXD_OBJECT_FUNC | AMXD_TEMPLATE_INFO,
                                 access,
                                 "functions");
}