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
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
Description:
Cancel attention on the domain, further changes will not be signaled.
Parameters:
char *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).
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
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.
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.
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
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
Description:
Returns the number of objects sets in the domain.
Parameters:
char *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
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
Description:
Cancel attention on the object set, further set changes will not be signaled.
Parameters:
int id
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
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
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
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.