Define RPC methods

Functions
amxd_status_t	amxd_function_new (amxd_function_t **func, const char *name, const uint32_t ret_type, amxd_object_fn_t impl)
	Data model RPC method constructor function. More...
void	amxd_function_delete (amxd_function_t **func)
	Data model RPC method destructor function. More...
amxd_status_t	amxd_function_copy (amxd_function_t **dest, const amxd_function_t *const source)
	Data model RPC method copy constructor function. More...
amxd_object_t *	amxd_function_get_owner (const amxd_function_t *const func)
	Get the object pointer of the object containing the function definition. More...
amxd_function_t *	amxd_function_get_base (const amxd_function_t *const func)
	Get the base function definition of an overridden function. More...
amxd_status_t	amxd_function_call_base (const amxd_function_t *const func, amxd_object_t *const object, amxc_var_t *const args, amxc_var_t *const ret)
	Call the base function of an overridden function. More...
const char *	amxd_function_get_name (const amxd_function_t *const func)
	Get the name of a method. More...
static uint32_t	amxd_function_get_type (const amxd_function_t *const func)
	Gets the return type of a method. More...
amxd_status_t	amxd_function_set_attr (amxd_function_t *func, const amxd_fattr_id_t attr, const bool enable)
	Sets or unsets a method attribute. More...
amxd_status_t	amxd_function_set_attrs (amxd_function_t *func, const uint32_t bitmask, bool enable)
	Sets or unsets method attributes using a bitmap. More...
uint32_t	amxd_function_get_attrs (const amxd_function_t *const func)
	Gets the set attributes of a RPC method. More...
bool	amxd_function_is_attr_set (const amxd_function_t *const func, const amxd_fattr_id_t attr)
	Checks if a method attribute is set. More...
void	amxd_function_set_flag (amxd_function_t *func, const char *flag)
	Sets a flag on a function. More...
void	amxd_function_unset_flag (amxd_function_t *func, const char *flag)
	Removes a flag from a function. More...
bool	amxd_function_has_flag (const amxd_function_t *const func, const char *flag)
	Checks if a flag is set. More...
amxd_status_t	amxd_function_set_impl (amxd_function_t *const func, amxd_object_fn_t impl)
	Set an implementation for a RPC method. More...
amxd_status_t	amxd_function_describe (amxd_function_t *const func, amxc_var_t *const value)
	Fetches the full RPC method definition in a variant. More...
amxd_status_t	amxd_function_defer (const amxd_function_t *const func, uint64_t *call_id, amxc_var_t *const ret, amxd_deferred_cancel_t cancel_fn, void *priv)
	Creates a deferred RPC context. More...
void	amxd_function_deferred_remove (uint64_t call_id)
	Removes a deferred RPC context. More...
void *	amxd_function_deferred_get_priv (uint64_t call_id)
	Gets the callee private data of an deferred function. More...
amxd_status_t	amxd_function_set_deferred_cb (uint64_t call_id, amxp_deferred_fn_t cb, void *priv)
	Sets a callback function to get the result of the deferred call. More...
amxd_status_t	amxd_function_deferred_done (uint64_t call_id, amxd_status_t status, amxc_var_t *out_args, amxc_var_t *ret)
	Finishes a deferred method and removes the deferred function context. More...
amxd_status_t	amxd_function_deferred_call_done (uint64_t call_id, amxd_status_t status, amxc_var_t *out_args, amxc_var_t *ret)
	Finishes a deferred method and removes the deferred function context. More...
amxd_status_t	amxd_function_new_arg (amxd_function_t *func, const char *name, const uint32_t type, amxc_var_t *default_value)
	Adds an argument definition to a RPC method definition. More...
void	amxd_function_del_arg (amxd_function_t *func, const char *name)
	Removes an argument definition from a RPC method definition. More...
amxd_func_arg_t *	amxd_function_get_arg (const amxd_function_t *const func, const char *name)
	Gets the argument definition of a RPC method. More...
amxd_status_t	amxd_function_arg_set_attr (amxd_function_t *const func, const char *name, const amxd_aattr_id_t attr, const bool enable)
	Sets or unsets a method argument attribute. More...
amxd_status_t	amxd_function_arg_set_attrs (amxd_function_t *func, const char *name, const uint32_t bitmask, bool enable)
	Sets or unsets method argument attributes using a bitmap. More...
bool	amxd_function_arg_is_attr_set (const amxd_function_t *const func, const char *name, const amxd_aattr_id_t attr)
	Checks if a method argument attribute is set. More...
amxd_status_t	amxd_function_arg_describe (amxd_func_arg_t *const arg, amxc_var_t *const value)
	Fetches the argument definition in a variant. More...
bool	amxd_function_are_args_valid (amxd_function_t *func, amxc_var_t *args)
	Validates that the input arguments are valid. More...

Detailed Description

Function Documentation

amxd_function_are_args_valid()

bool amxd_function_are_args_valid	(	amxd_function_t *	func,
		amxc_var_t *	args
	)

Validates that the input arguments are valid.

The arguments must be provided as a htable variant, where each argument is an entry in the hash table.

This function will check that:

1. all mandatory in arguments are provided
2. all strict typed arguments have the correct type information.

Missing optional arguments with a default value defined will be added to the htable variant.

Note

This function is not validating that the values of each individual argument are valid, it only verifies that all mandatory arguments with the correct type are present in the provided htable variant.

Parameters

func	pointer to a function definition
args	variant containing a htable with function arguments

Returns

true when the argument hash table is valid. false when the provided arguments are not valid, or NULL pointers are provided for the function definition or arguments variant.

Definition at line 486 of file amxd_function.c.

                                                    {
    bool valid = false;
 
    when_null(func, exit);
    when_null(args, exit);
    when_false(amxc_var_type_of(args) == AMXC_VAR_ID_HTABLE, exit);
 
    amxc_llist_for_each(it, (&func->args)) {
        amxd_func_arg_t* arg = amxc_llist_it_get_data(it, amxd_func_arg_t, it);
        amxc_var_t* in_arg = amxc_var_get_key(args,
                                              arg->name,
                                              AMXC_VAR_FLAG_DEFAULT);
        if(arg->attr.in == 0) {
            continue;
        }
        if(arg->attr.mandatory == 1) {
            when_null(in_arg, exit);
        }
        if((in_arg == NULL) &&
           ( amxc_var_type_of(&arg->default_value) != AMXC_VAR_ID_NULL)) {
            in_arg = amxc_var_add_new_key(args, arg->name);
            amxc_var_copy(in_arg, &arg->default_value);
        }
        if((arg->attr.strict == 1) &&
           ( in_arg != NULL)) {
            when_true(arg->type != amxc_var_type_of(in_arg), exit);
        }
    }
 
    valid = true;
 
exit:
    return valid;
}

amxd_function_arg_describe()

amxd_status_t amxd_function_arg_describe	(	amxd_func_arg_t *const	arg,
		amxc_var_t *const	value
	)

Fetches the argument definition in a variant.

It can be very handy to get the full definition of the argument.

This function is mainly intended for introspection.

Parameters

arg	pointer to a argument definition
value	variant where the argument defintion can be stored

Returns

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

Definition at line 278 of file amxd_function_args.c.

                                                                  {
    amxd_status_t status = amxd_status_unknown_error;
    amxc_var_t* table = NULL;
    uint32_t attrs = 0;
    static const char* attr_name[] = {
        "in",
        "out",
        "mandatory",
        "strict"
    };
 
    when_null(arg, exit);
    when_null(value, exit);
 
    amxc_var_set_type(value, AMXC_VAR_ID_HTABLE);
    amxc_var_add_key(cstring_t, value, "name", arg->name);
    amxc_var_add_key(uint32_t, value, "type_id", arg->type);
    amxc_var_add_key(cstring_t,
                     value,
                     "type_name",
                     amxc_var_get_type_name_from_id(arg->type));
    if(!amxc_var_is_null(&arg->default_value)) {
        amxc_var_set_key(value, "default", &arg->default_value, AMXC_VAR_FLAG_COPY);
    }
    table = amxc_var_add_key(amxc_htable_t, value, "attributes", NULL);
    attrs = amxd_function_arg_get_attributes(arg);
    for(int i = 0; i <= amxd_aattr_max; i++) {
        bool is_set = (attrs & (1 << i)) != 0 ? true : false;
        amxc_var_add_key(bool,
                         table,
                         attr_name[i],
                         is_set);
    }
 
    status = amxd_status_ok;
 
exit:
    return status;
}

amxd_function_arg_is_attr_set()

bool amxd_function_arg_is_attr_set	(	const amxd_function_t *const	func,
		const char *	name,
		const amxd_aattr_id_t	attr
	)

Checks if a method argument attribute is set.

The following attribute identifiers can be checked

• amxd_aattr_in
• amxd_aattr_out
• amxd_aattr_mandatory
• amxd_aattr_strict

Parameters

func	pointer to a function definition
name	the argument name
attr	the method attribute id

Returns

Returns true if attribute is set and false when unset

Definition at line 260 of file amxd_function_args.c.

                                                               {
    uint32_t flags = 0;
    amxd_func_arg_t* arg = NULL;
    bool retval = false;
    when_null(func, exit);
    when_true(attr < 0 || attr > amxd_aattr_max, exit);
 
    arg = amxd_function_get_arg(func, name);
    when_null(arg, exit);
    flags = amxd_function_arg_get_attributes(arg);
    retval = (flags & (1 << attr)) != 0 ? true : false;
 
exit:
    return retval;
}

amxd_function_arg_set_attr()

amxd_status_t amxd_function_arg_set_attr	(	amxd_function_t *const	func,
		const char *	name,
		const amxd_aattr_id_t	attr,
		const bool	enable
	)

Sets or unsets a method argument attribute.

The following attributes can be set - unset:

• amxd_aattr_in
• amxd_aattr_out
• amxd_aattr_mandatory
• amxd_aattr_strict

Parameters

func	pointer to a function definition
name	the argument name
attr	the attribute id
enable	when true, sets the attribute, when false unsets the attribute

Returns

Returns amxd_status_ok when attribute is changed, any other when failed

Definition at line 183 of file amxd_function_args.c.

                                                            {
    amxd_status_t retval = amxd_status_unknown_error;
    uint32_t flags = 0;
    amxd_func_arg_t* arg = NULL;
    when_null(func, exit);
 
    when_true_status(attr < 0 || attr > amxd_aattr_max,
                     exit,
                     retval = amxd_status_invalid_attr);
 
    arg = amxd_function_get_arg(func, name);
    when_null(arg, exit);
    flags = amxd_function_arg_get_attributes(arg);
 
    // when type any is set, it can not be a strict typed argument
    if((attr == amxd_aattr_strict) &&
       ( arg->type == AMXC_VAR_ID_ANY)) {
        retval = amxd_status_invalid_attr;
        goto exit;
    }
 
    if(enable) {
        flags |= (1 << attr);
    } else {
        flags &= ~(1 << attr);
    }
 
    amxd_function_arg_set_attributes(arg, flags);
    retval = amxd_status_ok;
 
exit:
    return retval;
}

amxd_function_arg_set_attrs()

amxd_status_t amxd_function_arg_set_attrs	(	amxd_function_t *	func,
		const char *	name,
		const uint32_t	bitmask,
		bool	enable
	)

Sets or unsets method argument attributes using a bitmap.

The following attributes can be set - unset:

• amxd_aattr_in
• amxd_aattr_out
• amxd_aattr_mandatory
• amxd_aattr_strict

Use the macro SET_BIT to transform the attribute id to a bit. The bits can be joined together using the bitwise or operator '|'

amxd_function_arg_set_attrs(func,
                            "number",
                            SET_BIT(amxd_aattr_in) |
                            SET_BIT(amxd_aattr_strict),
                            true);

When setting or unsetting one single attribute the function amxd_function_arg_set_attr can be used.

Parameters

func	pointer to a function definition
name	the argument name
bitmask	the function attribute bitmask
enable	when true, sets the attributes, when false unsets the attributes

Returns

Returns amxd_status_ok when attributes are changed, any other status when failed

Definition at line 220 of file amxd_function_args.c.

                                                       {
    amxd_status_t retval = amxd_status_unknown_error;
    uint32_t flags = 0;
    amxd_func_arg_t* arg = NULL;
    uint32_t all = 0;
 
    for(int i = 0; i <= amxd_aattr_max; i++) {
        all |= SET_BIT(i);
    }
 
    when_null(func, exit);
    when_true_status(bitmask > all, exit, retval = amxd_status_invalid_attr);
 
    arg = amxd_function_get_arg(func, name);
    when_null(arg, exit);
    flags = amxd_function_arg_get_attributes(arg);
 
    // when type any is set, it can not be a strict typed argument
    if(((bitmask & SET_BIT(amxd_aattr_strict)) != 0) &&
       ( arg->type == AMXC_VAR_ID_ANY)) {
        retval = amxd_status_invalid_attr;
        goto exit;
    }
 
    if(enable) {
        flags |= bitmask;
    } else {
        flags &= ~bitmask;
    }
 
    amxd_function_arg_set_attributes(arg, flags);
    retval = amxd_status_ok;
 
exit:
    return retval;
}

amxd_function_call_base()

amxd_status_t amxd_function_call_base	(	const amxd_function_t *const	func,
		amxd_object_t *const	object,
		amxc_var_t *const	args,
		amxc_var_t *const	ret
	)

Call the base function of an overridden function.

In derived objects it is possible to override methods and set a different implementation. Using this function the base implementation from which the method is derived is called.

Parameters

func	pointer to a function definition
object	the object on which the function must be called
args	htable variant containing the function arguments
ret	variant that can be filled with the function return data

Returns

amxd_status_ok when function was successful, or an other status when an error occured

Definition at line 260 of file amxd_function.c.

                                                             {
    amxd_status_t status = amxd_status_unknown_error;
    amxd_function_t* base_func = amxd_function_get_base(func);
 
    when_null(object, exit);
    when_null(base_func, exit);
    if(base_func->impl == NULL) {
        status = amxd_status_function_not_implemented;
        goto exit;
    }
    status = base_func->impl(object, base_func, args, ret);
 
exit:
    return status;
}

amxd_function_copy()

amxd_status_t amxd_function_copy	(	amxd_function_t **	dest,
		const amxd_function_t *const	source
	)

Data model RPC method copy constructor function.

Makes an exact deep copy a RPC method definition.

The newly created RPC method definition will not be added to any data model object, that can be done using amxd_object_add_function

Note

Derived objects are always inheriting the methods.

Parameters

dest	pointer to a pointer to the new RPC method definition (the copy)
source	pointer to a RPC method definition

Returns

amxd_status_ok when the function definition is created, or another status when an error has occurred.

Definition at line 181 of file amxd_function.c.

                                                                      {
    amxd_status_t retval = amxd_status_unknown_error;
    when_null(dest, exit);
    when_null(source, exit);
 
    *dest = (amxd_function_t*) calloc(1, sizeof(amxd_function_t));
    when_null((*dest), exit);
 
    when_failed(amxd_function_init(*dest, source->name,
                                   source->ret_type,
                                   source->impl), exit);
    (*dest)->attr = source->attr;
 
    amxc_llist_for_each(it, (&source->args)) {
        amxd_func_arg_t* arg = amxc_llist_it_get_data(it, amxd_func_arg_t, it);
        when_failed(amxd_function_new_arg((*dest),
                                          arg->name,
                                          arg->type,
                                          &arg->default_value), exit);
        if(amxd_function_arg_is_attr_set(source, arg->name, amxd_aattr_in)) {
            amxd_function_arg_set_attr((*dest), arg->name, amxd_aattr_in, true);
        }
        if(amxd_function_arg_is_attr_set(source, arg->name, amxd_aattr_out)) {
            amxd_function_arg_set_attr((*dest), arg->name, amxd_aattr_out, true);
        }
        if(amxd_function_arg_is_attr_set(source, arg->name, amxd_aattr_mandatory)) {
            amxd_function_arg_set_attr((*dest), arg->name, amxd_aattr_mandatory, true);
        }
        if(amxd_function_arg_is_attr_set(source, arg->name, amxd_aattr_strict)) {
            amxd_function_arg_set_attr((*dest), arg->name, amxd_aattr_strict, true);
        }
    }
 
    retval = amxd_status_ok;
 
exit:
    if((retval != amxd_status_ok) && (dest != NULL) && (*dest != NULL)) {
        amxd_function_clean(*dest);
        free(*dest);
        *dest = NULL;
    }
    return retval;
}

amxd_function_defer()

amxd_status_t amxd_function_defer	(	const amxd_function_t *const	func,
		uint64_t *	call_id,
		amxc_var_t *const	ret,
		amxd_deferred_cancel_t	cancel_fn,
		void *	priv
	)

Creates a deferred RPC context.

If an RPC method can take a while before it can return the result, it can reply the result later (ie asynchronous I/O). To indicate the result will be available later, the RPC method must return status amxd_status_deferred and must call this function before returning.

When the result is available (ie asynchronous I/O is done), the method amxd_function_deferred_done must be called.

It is also possible to remove the deferred call by calling amxd_function_deferred_remove. This will send an error back to the caller.

Parameters

func	pointer to a function definition
call_id	each deferred method gets a call_id, it will be filled in this integer. The call_id is needed in all other calls related to deferred RPC methods
ret	The call id will also be filled in the return value of the RPC method. This will enable the caller to add a callback function to get informed when the result is available.
cancel_fn	Optionally a cancel callback function can be given. This will be called when the deferred function is removed.
priv	Some private data for the callee, will be provided to the cancel callback function. Typically used to be able to free allocated memory when the deferred function is canceled.

Returns

amxd_status_ok when the deferred context is created or another status when an error has occurred.

Definition at line 126 of file amxd_function_deferred.c.

                                              {
    amxd_status_t status = amxd_status_unknown_error;
    amxd_deferred_ctx_t* call = NULL;
 
    when_null(func, exit);
    when_null(ret, exit);
    when_null(call_id, exit)
 
    call = (amxd_deferred_ctx_t*) calloc(1, sizeof(amxd_deferred_ctx_t));
    when_null(call, exit);
 
    call->call_id = g_call_id++;
    call->called_priv = priv;
    call->cancel = cancel_fn;
    amxc_llist_append(&deferred, &call->it);
    amxc_var_set(uint64_t, ret, call->call_id);
    *call_id = call->call_id;
 
    status = amxd_status_ok;
 
exit:
    return status;
}

amxd_function_deferred_call_done()

amxd_status_t amxd_function_deferred_call_done	(	uint64_t	call_id,
		amxd_status_t	status,
		amxc_var_t *	out_args,
		amxc_var_t *	ret
	)

Finishes a deferred method and removes the deferred function context.

When the result is available, a callee can finish the deferred method by calling this function. It must provide the final status and the return value.

This will trigger the callback function registered by the caller. The callback function will be called immediately.

Parameters

call_id	The id of the deferred function.
status	The final status of the RPC method
out_args	Out arguments if any (can be NULL)
ret	The return value of the RPC method

Returns

amxd_status_ok if the reply was sent or another status when an error has occured.

Definition at line 249 of file amxd_function_deferred.c.

                                                                {
    return amxd_function_deferred_done_impl(call_id, status, out_args, ret, true);
}

amxd_function_deferred_done()

amxd_status_t amxd_function_deferred_done	(	uint64_t	call_id,
		amxd_status_t	status,
		amxc_var_t *	out_args,
		amxc_var_t *	ret
	)

Finishes a deferred method and removes the deferred function context.

When the result is available, a callee can finish the deferred method by calling this function. It must provide the final status and the return value.

This will trigger the callback function registered by the caller. The callback function will be called from the eventloop, in other words the callback function is scheduled to be called and is not called immediately.

Parameters

call_id	The id of the deferred function.
status	The final status of the RPC method
out_args	Out arguments if any (can be NULL)
ret	The return value of the RPC method

Returns

amxd_status_ok if the reply was send or another status when an error has occured.

Definition at line 242 of file amxd_function_deferred.c.

                                                           {
    return amxd_function_deferred_done_impl(call_id, status, out_args, ret, false);
}

amxd_function_deferred_get_priv()

void* amxd_function_deferred_get_priv

(

uint64_t

call_id

)

Gets the callee private data of an deferred function.

When a callee creates a deferred function contexts it can provide private data. Using this method it can retrieve the private data using the deferred call id.

Parameters

call_id

The id of the deferred function.

Returns

The private data that was set with amxd_function_defer

Definition at line 173 of file amxd_function_deferred.c.

                                                        {
    void* data = NULL;
    amxd_deferred_ctx_t* call = amxd_find_deferred(call_id);
 
    when_null(call, exit);
    data = call->called_priv;
 
exit:
    return data;
}

amxd_function_deferred_remove()

void amxd_function_deferred_remove

(

uint64_t

call_id

)

Removes a deferred RPC context.

A deferred function context can be removed by the caller or the callee.

When the caller wants to remove a deferred function its deferred callback must be removed first.

If the callee wants to remove a deferred function its cancel callback must be removed first.

Parameters

call_id

The id of the deferred function.

Definition at line 154 of file amxd_function_deferred.c.

                                                     {
    amxd_deferred_ctx_t* call = amxd_find_deferred(call_id);
    amxc_var_t sig_data;
 
    amxc_var_init(&sig_data);
    when_null(call, exit);
 
    amxc_var_set_type(&sig_data, AMXC_VAR_ID_HTABLE);
    amxc_var_add_new_key(&sig_data, "retval");
    amxc_var_add_key(uint32_t, &sig_data, "status", amxd_status_unknown_error);
 
    amxd_cancel_deferred(call, &sig_data);
    amxd_delete_deferred(&call->it);
 
exit:
    amxc_var_clean(&sig_data);
    return;
}

amxd_function_del_arg()

void amxd_function_del_arg	(	amxd_function_t *	func,
		const char *	name
	)

Removes an argument definition from a RPC method definition.

Parameters

func	pointer to a function definition
name	the argument name

Definition at line 168 of file amxd_function_args.c.

                                                                    {
    amxd_func_arg_t* arg = NULL;
    when_null(func, exit);
    when_str_empty(name, exit);
 
    arg = amxd_function_get_arg(func, name);
    when_null(arg, exit);
 
    amxd_function_arg_clean(arg);
    free(arg);
 
exit:
    return;
}

amxd_function_delete()

void amxd_function_delete

(

amxd_function_t **

func

)

Data model RPC method destructor function.

Frees all memory allocated to store the RPC method definition.

If the RPC method was added to a data model object using amxd_object_add_function, the RPC method is removed from that object.

Warning

Removing a RPC method from an object will affect all derived objects as well.

Parameters

func	pointer to a pointer to the RPC method definition

Definition at line 169 of file amxd_function.c.

                                                  {
    when_null(func, exit);
    when_null((*func), exit);
 
    amxd_function_clean((*func));
    free(*func);
    *func = NULL;
 
exit:
    return;
}

amxd_function_describe()

amxd_status_t amxd_function_describe	(	amxd_function_t *const	func,
		amxc_var_t *const	value
	)

Fetches the full RPC method definition in a variant.

It can be very handy to get the full definition of the RPC method.

This function is mainly intended for introspection.

Parameters

func	pointer to a function definition
value	variant where the RPC method defintion can be stored

Returns

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

Definition at line 413 of file amxd_function.c.

                                                              {
    amxd_status_t status = amxd_status_unknown_error;
    amxc_var_t* table = NULL;
    uint32_t retvalt = 0;
 
    static const char* attr_name[] = {
        "template",
        "instance",
        "private",
        "protected",
        "asynchronous",
    };
 
    when_null(func, exit);
    when_null(value, exit);
 
    retvalt = amxd_function_get_type(func);
    amxc_var_set_type(value, AMXC_VAR_ID_HTABLE);
    amxc_var_add_key(cstring_t, value, "name", amxd_function_get_name(func));
    amxc_var_add_key(uint32_t, value, "type_id", retvalt);
    amxc_var_add_key(cstring_t,
                     value,
                     "type_name",
                     amxc_var_get_type_name_from_id(retvalt));
    table = amxc_var_add_key(amxc_htable_t, value, "attributes", NULL);
    for(int i = 0; i <= (int) amxd_fattr_max; i++) {
        amxc_var_add_key(bool,
                         table,
                         attr_name[i],
                         amxd_function_is_attr_set(func, (amxd_fattr_id_t) i));
    }
 
    table = amxc_var_add_key(amxc_llist_t, value, "arguments", NULL);
    amxc_llist_for_each(it, (&func->args)) {
        amxd_func_arg_t* farg = amxc_llist_it_get_data(it, amxd_func_arg_t, it);
        amxc_var_t* arg = amxc_var_add(amxc_htable_t, table, NULL);
        amxd_function_arg_describe(farg, arg);
    }
 
    table = amxc_var_add_key(amxc_llist_t, value, "flags", NULL);
    if(func->flags != NULL) {
        amxc_var_for_each(flag, func->flags) {
            if(amxc_var_dyncast(bool, flag)) {
                amxc_var_add(cstring_t, table, amxc_var_key(flag));
            }
        }
    }
 
    status = amxd_status_ok;
 
exit:
    return status;
}

amxd_function_get_arg()

amxd_func_arg_t* amxd_function_get_arg	(	const amxd_function_t *const	func,
		const char *	name
	)

Gets the argument definition of a RPC method.

Parameters

func	pointer to a function definition
name	the argument name

Returns

amxd_status_ok when the argument is removed from the RPC method, or another status when an error has occurred.

Definition at line 468 of file amxd_function.c.

                                                         {
    amxd_func_arg_t* arg = NULL;
    when_null(func, exit);
    when_str_empty(name, exit);
 
    amxc_llist_for_each(it, (&func->args)) {
        arg = amxc_llist_it_get_data(it, amxd_func_arg_t, it);
        if(strcmp(arg->name, name) == 0) {
            break;
        }
        arg = NULL;
    }
 
exit:
    return arg;
}

amxd_function_get_attrs()

uint32_t amxd_function_get_attrs

(

const amxd_function_t *const

func

)

Gets the set attributes of a RPC method.

This function returns the set attributes of a method as a bitmask. To verify if a certain attribute is set, use the macro IS_BIT_SET.

uint32_t attrs = amxd_function_get_attrs(func);
 
if(IS_BIT_SET(attrs, amxd_fattr_instance)) {
    // do something
}

To verify that one single attribute is set the function amxd_function_is_attr_set can be used.

Parameters

func	pointer to a function definition

Returns

Returns the attributes set on the method as a bitmask.

Definition at line 339 of file amxd_function.c.

                                                                    {
    uint32_t attributes = 0;
    when_null(func, exit);
 
    attributes |= func->attr.templ << amxd_fattr_template;
    attributes |= func->attr.instance << amxd_fattr_instance;
    attributes |= func->attr.priv << amxd_fattr_private;
    attributes |= func->attr.prot << amxd_fattr_protected;
    attributes |= func->attr.async << amxd_fattr_async;
 
exit:
    return attributes;
}

amxd_function_get_base()

amxd_function_t* amxd_function_get_base

(

const amxd_function_t *const

func

)

Get the base function definition of an overridden function.

In derived objects it is possible to override methods and set a different implementation. Using this function the base definition from which the method is derived is returned.

Parameters

func	pointer to a function definition

Returns

The function definition pointer of the base definition, if there is no base definition, the given definition pointer is returned.

Definition at line 237 of file amxd_function.c.

                                                                           {
    amxd_function_t* base = NULL;
    amxd_object_t* object = amxd_function_get_owner(func);
 
    when_null(object, exit);
 
    if(amxd_object_get_type(object) == amxd_object_instance) {
        base = amxd_object_get_function(amxd_object_get_parent(object),
                                        func->name);
    } 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);
            base = amxd_object_get_function(super, func->name);
        }
    }
 
exit:
    return base;
}

amxd_function_get_name()

const char* amxd_function_get_name

(

const amxd_function_t *const

func

)

Get the name of a method.

Returns the name of the method. There is no need to free the returned pointer.

Parameters

func	pointer to a function definition

Returns

The name of the method.

Definition at line 279 of file amxd_function.c.

                                                                      {
    return func == NULL ? NULL : func->name;
}

amxd_function_get_owner()

amxd_object_t* amxd_function_get_owner

(

const amxd_function_t *const

func

)

Get the object pointer of the object containing the function definition.

When using a derived object, the object containing the function defintion can be different than the object where the function definition pointer was retrieved from.

It is possible to change the implementation of the method in a derived object. This can be done using amxd_object_change_function. When changing the implementation in a derived object, a copy of the function definition is created and stored in the derived object. To retrieve the base implementation use amxd_function_get_base.

Parameters

func	pointer to a function definition

Returns

The object pointer containing the method definition, or NULL if the object definition is not owned by an object.

Definition at line 226 of file amxd_function.c.

                                                                          {
    amxd_object_t* object = NULL;
    when_null(func, exit);
    when_null(func->it.llist, exit);
 
    object = amxc_container_of(func->it.llist, amxd_object_t, functions);
 
exit:
    return object;
}

amxd_function_get_type()

static uint32_t amxd_function_get_type ( const amxd_function_t *const  func )

inlinestatic

Gets the return type of a method.

Returns the return type of a method. The return type matches with a amxc variant type.

Parameters

func	pointer to a function definition

Returns

The return type of the method.

Definition at line 260 of file amxd_function.h.

                                                                   {
    return func == NULL ? AMXC_VAR_ID_NULL : func->ret_type;
}

amxd_function_has_flag()

bool amxd_function_has_flag	(	const amxd_function_t *const	func,
		const char *	flag
	)

Checks if a flag is set.

A flag is any arbitrary string and can be set or unset.

The flags set on a function can be seen in the description data of the function.

When a derived object overrides a function, the flags are reset for that derived object.

Parameters

func	pointer to a function definition
flag	the flag name

Returns

true when the flag is set

Definition at line 389 of file amxd_function.c.

                                                                                 {
    bool retval = false;
    when_null(func, exit);
    when_null(flag, exit);
    when_true(*flag == 0, exit);
 
    retval = amxd_common_has_flag(func->flags, flag);
 
exit:
    return retval;
}

amxd_function_is_attr_set()

bool amxd_function_is_attr_set	(	const amxd_function_t *const	func,
		const amxd_fattr_id_t	attr
	)

Checks if a method attribute is set.

The following attribute identifiers can be checked

• amxd_fattr_template
• amxd_fattr_instance
• amxd_fattr_private
• amxd_fattr_protected

Parameters

func	pointer to a function definition
attr	the method attribute id

Returns

Returns true if attribute is set and false when unset

Definition at line 353 of file amxd_function.c.

                                                           {
    uint32_t flags = 0;
    bool retval = false;
    when_null(func, exit);
    when_true(attr < 0 || attr > amxd_fattr_max, exit);
 
    flags = amxd_function_get_attributes(func);
    retval = (flags & (1 << attr)) != 0 ? true : false;
 
exit:
    return retval;
}

amxd_function_new()

amxd_status_t amxd_function_new	(	amxd_function_t **	func,
		const char *	name,
		const uint32_t	ret_type,
		amxd_object_fn_t	impl
	)

Data model RPC method constructor function.

Allocates memory for a new data model rpc method and initializes the struct _amxd_function.

Creates a RPC method definition. Each RPC method has a return type and must be one of the available amxc variant types. A name must be provided as well.

When adding the rpc method to an object using amxd_object_add_function the name of the RPC method should not exist in that object as a RPC method.

Optionally a function pointer can be provided. If no function implementation is set, the function definition exists, but calling the function will fail.

Function implementation must match with this prototype definition:

typedef amxd_status_t (* amxd_object_fn_t) (amxd_object_t* object,
                                            amxd_function_t* func,
                                            amxc_var_t* args,
                                            amxc_var_t* ret);

To be able to call the function it must be added to an object.

When the RPC method definition is not added to any data model object, the pointer must be freed using amxd_function_delete.

When the RPC method definition is added to a data model object, it will be automatically freed when the object that contains the method is deleted.

Parameters

func	pointer to a pointer to the new RPC method definition
name	the name of the RPC method
ret_type	the return type of the RPC method, must be a valid amxc variant type
impl	pointer to the implementation function

Returns

amxd_status_ok when the function definition is created, or another status when an error has occurred.

Definition at line 146 of file amxd_function.c.

                                                       {
    amxd_status_t retval = amxd_status_unknown_error;
    when_null(func, exit);
    when_true_status(!amxd_name_is_valid(name),
                     exit,
                     retval = amxd_status_invalid_name);
 
    *func = (amxd_function_t*) calloc(1, sizeof(amxd_function_t));
    when_null((*func), exit);
 
    retval = amxd_function_init(*func, name, ret_type, impl);
 
exit:
    if((retval != 0) && (func != NULL)) {
        free(*func);
        *func = NULL;
    }
    return retval;
}

amxd_function_new_arg()

amxd_status_t amxd_function_new_arg	(	amxd_function_t *	func,
		const char *	name,
		const uint32_t	type,
		amxc_var_t *	default_value
	)

Adds an argument definition to a RPC method definition.

Parameters

func	pointer to a function definition
name	the argument name
type	the argument type, must be one of the amxc variant types
default_value	a default value for the argument

Returns

amxd_status_ok when the argument is added to the RPC method, or another status when an error has occurred.

Definition at line 140 of file amxd_function_args.c.

                                                               {
    amxd_status_t retval = amxd_status_unknown_error;
    amxd_func_arg_t* arg = NULL;
    when_null(func, exit);
 
    when_str_empty_status(name, exit, retval = amxd_status_invalid_name);
    when_true_status(!amxd_function_arg_valid_name(func, name),
                     exit,
                     retval = amxd_status_invalid_name);
 
    arg = (amxd_func_arg_t*) calloc(1, sizeof(amxd_func_arg_t));
    when_null(arg, exit);
 
    retval = amxd_function_arg_init(arg, name, type, default_value);
 
    if(retval == amxd_status_ok) {
        amxc_llist_append(&func->args, &arg->it);
    }
exit:
    if(retval != amxd_status_ok) {
        free(arg);
    }
    return retval;
}

amxd_function_set_attr()

amxd_status_t amxd_function_set_attr	(	amxd_function_t *	func,
		const amxd_fattr_id_t	attr,
		const bool	enable
	)

Sets or unsets a method attribute.

The following attributes can be set - unset:

• amxd_fattr_template
• amxd_fattr_instance
• amxd_fattr_private
• amxd_fattr_protected

Note

The attributes amxd_fattr_template and amxd_fattr_instance are ignored when the method is added to a singleton object.

Parameters

func	pointer to a function definition
attr	the attribute id
enable	when true, sets the attribute, when false unsets the attribute

Returns

Returns amxd_status_ok when attribute is changed, any other when failed

Definition at line 283 of file amxd_function.c.

                                                        {
    amxd_status_t retval = amxd_status_unknown_error;
    uint32_t flags = 0;
    when_null(func, exit);
 
    when_true_status(attr < 0 || attr > amxd_fattr_max,
                     exit,
                     retval = amxd_status_invalid_attr);
 
    flags = amxd_function_get_attributes(func);
 
    if(enable) {
        flags |= (1 << attr);
    } else {
        flags &= ~(1 << attr);
    }
 
    amxd_function_set_attributes(func, flags);
 
    retval = amxd_status_ok;
 
exit:
    return retval;
}

amxd_function_set_attrs()

amxd_status_t amxd_function_set_attrs	(	amxd_function_t *	func,
		const uint32_t	bitmask,
		bool	enable
	)

Sets or unsets method attributes using a bitmap.

The following attributes can be set - unset:

• amxd_fattr_template
• amxd_fattr_instance
• amxd_fattr_private
• amxd_fattr_protected

Use the macro SET_BIT to transform the attribute id to a bit. The bits can be joined together using the bitwise or operator '|'

amxd_function_set_attrs(func,
                        SET_BIT(amxd_fattr_template) |
                        SET_BIT(amxd_fattr_instance),
                        true);

When setting or unsetting one single attribute the function amxd_function_set_attr can be used.

Note

The attributes amxd_fattr_template and amxd_fattr_instance are ignored when the method is added to a singleton object.

Parameters

func	pointer to a function definition
bitmask	the function attribute bitmask
enable	when true, sets the attributes, when false unsets the attributes

Returns

Returns amxd_status_ok when attributes are changed, any other status when failed

Definition at line 310 of file amxd_function.c.

                                                   {
    amxd_status_t retval = amxd_status_unknown_error;
    uint32_t flags = 0;
    uint32_t all = 0;
 
    for(int i = 0; i <= amxd_fattr_max; i++) {
        all |= SET_BIT(i);
    }
 
    when_null(func, exit);
    when_true_status(bitmask > all, exit, retval = amxd_status_invalid_attr);
 
    flags = amxd_function_get_attributes(func);
 
    if(enable) {
        flags |= bitmask;
    } else {
        flags &= ~bitmask;
    }
 
    amxd_function_set_attributes(func, flags);
    retval = amxd_status_ok;
 
exit:
    return retval;
}

amxd_function_set_deferred_cb()

amxd_status_t amxd_function_set_deferred_cb	(	uint64_t	call_id,
		amxp_deferred_fn_t	cb,
		void *	priv
	)

Sets a callback function to get the result of the deferred call.

When a caller invokes an object method with amxd_object_invoke_function and gets amxd_status_defer as status code, the caller can set a callback function that will be called when the deferred methods finishes.

The call identifier will be provided in the return value.

Parameters

call_id	The id of the deferred function.
cb	The callback function
priv	Some private data, will be passed to the callback function

Returns

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

Definition at line 184 of file amxd_function_deferred.c.

                                                        {
    amxd_status_t rv = amxd_status_invalid_function;
    amxd_deferred_ctx_t* call = amxd_find_deferred(call_id);
 
    when_null(call, exit);
 
    call->cb = cb;
    call->caller_priv = priv;
 
    rv = amxd_status_ok;
 
exit:
    return rv;
}

amxd_function_set_flag()

void amxd_function_set_flag	(	amxd_function_t *	func,
		const char *	flag
	)

Sets a flag on a function.

A flag is any arbitrary string and can be set or unset.

The flags set on a function can be seen in the description data of the function.

When a derived object overrides a function, the flags are reset for that derived object.

Parameters

func	pointer to a function definition
flag	the flag name

Definition at line 367 of file amxd_function.c.

                                                                     {
    when_null(func, exit);
    when_null(flag, exit);
    when_true(*flag == 0, exit);
 
    amxd_common_set_flag(&func->flags, flag);
 
exit:
    return;
}

amxd_function_set_impl()

amxd_status_t amxd_function_set_impl	(	amxd_function_t *const	func,
		amxd_object_fn_t	impl
	)

Set an implementation for a RPC method.

Data model object can contain methods. Remote clients can invoke these methods. An implementation must be set, the implementation must match with this prototype:

amxd_status_t <FUNCTION NAME>(amxd_object_t* object,
                              amxd_function_t* func,
                              amxc_var_t* args,
                              amxc_var_t* ret);

Note

When changing the method implementation with this function, and the method is added to an object that has derived objects the implementation is changed for all these object. To change the implementation for one single derived object use amxd_object_change_function.

Parameters

func	pointer to a function definition
impl	function pointer to the implementation

Returns

Returns amxd_status_ok when implementation is set, any other status code when failed.

Definition at line 401 of file amxd_function.c.

                                                            {
    amxd_status_t retval = amxd_status_unknown_error;
    when_null(func, exit);
 
    func->impl = impl;
    retval = amxd_status_ok;
 
exit:
    return retval;
}

amxd_function_unset_flag()

void amxd_function_unset_flag	(	amxd_function_t *	func,
		const char *	flag
	)

Removes a flag from a function.

A flag is any arbitrary string and can be set or unset.

The flags set on a function can be seen in the description data of the function.

When a derived object overrides a function, the flags are reset for that derived object.

Parameters

func	pointer to a function definition
flag	the flag name

Definition at line 378 of file amxd_function.c.

                                                                       {
    when_null(func, exit);
    when_null(flag, exit);
    when_true(*flag == 0, exit);
 
    amxd_common_unset_flag(&func->flags, flag);
 
exit:
    return;
}