7 SMIUIRTL Description

SMIUIRTL implements the routines used by a user interface or any other process wanting to get information on the states of objects running in a certain SM and/or to send commands to them.

The categories of routines are the following:

The routines are:

Parametes:

char *obj_name The name of the object in the form <domain_name>::<object_name>

char *state The buffer where the state will be stored on return.

char *busy_action If the object is busy the name of the action it is currently executing, otherwise a null string.

Description:

Used to know the current state of an object in a given domain. It also returns information on whether the object is busy executing an action or idle.

Parameters:

char *obj_name The name of the object in the form <domain_name>::<object_name>

char *cmnd The cmnd in the form action/par="val"…

Description:

Used to send a command to any object in any domain.

Parameters:

char *domain The name of the domain to connect to.

Description:

Used to connect to a specific domain, it's a blocking call, it waits until the domain responds. It returns the number of objects in the domain or 0 if it fails. The calls smiui_get_next_object, smiui_get_next_objectset call smiui_connect_domain implicitly if not done before.

Parameters:

char *domain The name of the domain.

void (*domainchange_handler)() The routine to handle domain changes

long param A parameter to pass to the above routine

Description:

Set up a callback routine to be called whenever the domain starts or stops. The domainchange_handler routine will be called with two parameters: param and the number of objects in the domain - both parameters are passed by reference.

Parameters:

char *domain  The name of the domain.

Description:

Cancel attention on the domain, further changes will not be signaled.

Parameters:

char *domain The name of the domain.

Description:

Returns the number of objects in the domain or 0 if it fails.

Parameters:

char *domain The name of the domain.

char *obj_name The name of the object in the form <domain_name>::<object_name>.

Description:

Get the name of the next object in a domain (several domains can be accessed at the "same time"). This routine returns 0 when all the objects of a particular domain have been retrieved

Parameters:

char *obj_name The name of the object.

void (*statechange_handler)() The routine to handle state changes

long param A parameter to pass to the above routine

Description:

Set up a callback routine to be called whenever the specified object changes state. smiui_book_statechange returns an identifier that should be used on the following calls. The statechange_handler routine will be called with two parameters: the address of the identifier mentioned above and the address of param (i.e. both parameters are passed by reference).

See the Example for clarification

Parameters:

int id The identifier returned by the previous call.

Description:

Cancel attention on the object, further state changes will not be signaled.

Parameters:

int id The identifier returned by smiui_book_statechange

char *obj_name Returns the name of the current object

Description:

This routine is normally called from the statechange_handler routine in order to get the name of the current object.

See the Example for clarification

Parameters:

int id The identifier returned by smiui_book_statechange.

int *busy_flag Returns a flag indicating if the current object is busy

char *state Returns the current state of the object

int *n_actions Returns the number of possible actions in the object’s current state

Description:

This routine is normally called from the statechange_handler routine in order to get the object state and some additional parameters.

See the Example for clarification

Parameters:

int id The identifier returned by smiui_book_statechange.

char *action The action currently being executed.

Description:

Called in order to get the action currently being executed by an object whenever the busy_flag in the previous routine is 1.

Parameters:

int id The identifier returned by smiui_book_statechange.

char *action The action name.

int n_pars The number of parameters this action takes.

Description:

This routine retrieves the next action available to an object in the current state.

Parameters:

int id The identifier returned by smiui_book_statechange.

char *action The action name.

int n_pars The number of parameters this action takes

Description:

Positions the next_action pointer back to the first action and retrieves it. smiui_get_next_action can be called again from then on.

Parameters:

int id The identifier returned by smiui_book_statechange.

char *param The action’s parameter name.

int *type The parameter type (SMI_STRING, SMI_ INTEGER, SMI_ FLOAT)

int *default_value_size The size of the parameter's default value if a default has been specified, otherwise 0.

Description:

This routine retrieves the next parameter specified for the current action available to an object in the current state. It returns 0 when all parameters have been returned.

Parameters:

int id The identifier returned by smiui_book_statechange.

void *default_value The parameter’s default value.

Description:

This routine retrieves the parameter default value, for the parameter received from smiui_get_next_param. This routine should only be called if default_value_size was not zero. It returns 0 if the parameter did not have a default value. The contents of default_value can be of type integer, float or character string according to the previous routine.

                    Parameters:

                                        int id The identifier returned by smiui_book_statechange.

                                        char *param The object’s parameter name.

                                        int *type The parameter type (SMI_STRING, SMI_ INTEGER, SMI_ FLOAT)

                                        int *value_size The size of the parameter's value.

                    Description:

                                        This routine retrieves the next parameter specified for the current object.
                                        It returns 0 when all parameters have been returned.

Parameters:

int id The identifier returned by smiui_book_statechange.

void *value The parameter’s value.

Description:

This routine retrieves the parameter value, for the parameter received from smiui_get_next_obj_param. The contents of value can be of type integer, float or character string according to the previous routine.

Parameters:

char *domain The name of the domain.

Description:

Returns the number of objects sets in the domain.

Parameters:

char *domain The name of the domain.

char *objset_name The name of the object set in the form <domain_name>::<objectset_name>.

Description:

Get the name of the next object set in a domain (several domains can be accessed at the "same time"). This routine returns 0 when all the object sets of a particular domain have been retrieved

Parameters:

char *objset_name The name of the object set.

void (*objectsetchange_handler)() The routine to handle changes in the contents of the set.

long param A parameter to pass to the above routine

Description:

Set up a callback routine to be called whenever the specified object set changes (i.e. objects are added or removed from the set). smiui_book_objectsetchange returns an identifier that should be used on the following calls. The objectsetchange_handler routine will be called with two parameters: the address of the identifier mentioned above and the address of param (i.e. both parameters are passed by reference).

Parameters:

int id The identifier returned by the previous call.

Description:

Cancel attention on the object set, further set changes will not be signaled.

Parameters:

int id The identifier returned by smiui_book_objectsetchange

char *objset_name Returns the name of the current object set

Description:

This routine is normally called from the objectsetchange_handler routine in order to get the name of the current object set.

Parameters:

int id The identifier returned by smiui_book_objectsetchange.

char *object The object name.

Description:

This routine retrieves the next object contained in the current object set, to be called from within objectsetchange_handler.

Parameters:

int id The identifier returned by smiui_book_objectsetchange.

char *object The object name.

Description:

Positions the next_object pointer back to the first object is the set and retrieves it. smiui_get_next_object_in_set can be called again from then on.

Parameters:

char *domain The SMI domain name.

void (*alloc_statechange_handler)() The routine to handle state changes

long param A parameter to pass to the above routine

Description:

Set up a callback routine to be called whenever the allocation state of the specified domain changes state. smiui_book_alloc_statechange returns an identifier that should be used on the following calls.The alloc_statechange_handler routine will be called with two parameters: the address of the identifier mentioned above and the address of param (i.e. both parameters are passed by reference).

Parameters:

int id The identifier returned by the previous call.

Description:

Cancel attention on the allocation state of the domain, further state changes will not be signalled.

Parameters:

int id The identifier returned by smiui_book_alloc_statechange.

int *busy_flag Returns a flag indicating if the domain allocation object is currently busy

char *state Returns the current state of the allocation object

Description:

This routine is normally called from the alloc_statechange_handler routine in order to get the allocation state of the domain.

Parameters:

char *domain The domain name.

Description:

This routine can be used by a user interface or another process in order to allocate an SMI domain to itself. An smiui_connect_domain should have been done before hand. Smiui_allocate domain returns 1 if the domain was successfully allocated and 0 if it was not connected or already allocated to someone else.

Parameters:

char *domainA The domain to be allocated.

char *domainB The domain to allocate to.

Description:

This routine can be used by a user interface or another process in order to allocate an SMI domain to another SMI domain. An smiui_connect_domain should have been done before hand to the allocator domain (domainB). Smiui_allocate domain returns 1 if domainA was successfully allocated to domainB and 0 if it domainB was not connected or domainA already allocated to someone else.

Parameters:

char *domain The domain name.

Description:

This routine can be used by a user interface or another process in order to release a previously allocated SMI domain. An smiui_connect_domain should have been done before hand. Smiui_release domain returns 1 if the domain was successfully released and 0 if the domain was not allocated to this process.

Parameters:

char *domainA The domain allocated.

char *domainB The domain that allocated domainA.

Description:

This routine can be used by a user interface or another process in order to release a domain from another one. An smiui_connect_domain should have been done before hand to domainB. Smiui_release domain returns 1 if domainA was successfully released from domainB and 0 if domainA was not allocated to domainB.