Ucs_Return_t Ucs_Rm_SetRouteActive	(	Ucs_Inst_t *	self,
		Ucs_Rm_Route_t *	route_ptr,
		bool	active
	)

Sets the given route to active respectively inactive and triggers the routing process to handle the route.

When setting a route to active the routing process will start building the route and all related resources and return the result to the user callback function (Refer to Routing Management Init Structure). When setting a route to inactive the routing process will start destroying the route and all related resources and return the result to the user callback function.

Parameters

self	The UNICENS instance.
route_ptr	Reference to the routes to be destroyed.
active	Specifies whether the route should be activated or not. true is active and false inactive.

Returns

Possible return values are shown in the table below.

Value	Description
UCS_RET_SUCCESS	No error
UCS_RET_ERR_PARAM	At least one parameter is NULL.
UCS_RET_ERR_ALREADY_SET	The given route is already active or inactive
UCS_RET_ERR_NOT_INITIALIZED	UNICENS is not initialized

Note

The build up or the destruction of a route can take some times in case the routing process may need to perform retries when uncritical errors occur (e.g.: transmission error, processing error, etc.) or when certain conditions are not met yet (e.g. network not available, node not available, etc.). By the way, the maximum number of retries is 0xFF and the minimum time between the retries is 50ms. This results in a minimum time of ca. 13s to get a route built or suspended (if the maximum retries are reached).

Attention

To suit your specific system needs and setup, change the default values of the following Resources Management macros:

• UCS_NUM_REMOTE_DEVICES in ucs_cfg.h
• UCS_XRM_NUM_JOBS in ucs_xrm_cfg.h
• UCS_XRM_NUM_RESOURCES in ucs_xrm_cfg.h

Use the UCS_ADDR_LOCAL_DEV macro to address the local device when specifying connection routes to or from this device.
The following address ranges are supported:

• [0x10 ... 0x2FF]
• [0x500 ... 0xFEF]
• UCS_ADDR_LOCAL_DEV

Example

// The report callback function for all routes
static void App_OnRoutingResult(uint16_t route_id, Ucs_Rm_RouteInfos_t route_infos, void *user_ptr)
{
      // Print whatever needs to be printed here
}

// Activates or deactivates the route with Index 2 of the routes list.
static void App_SetRouteId2_OnOff(bool active)
{
      Ucs_Return_t ret_value;

      ret_value = Ucs_Rm_SetRouteActive(ucs_inst_ptr, &routes_list[2], active);
      if (ret_value != UCS_RET_SUCCESS)
      {
          // Do whatever is necessary
      }
}

// Main function
void main(uint8_t argc, char *argv[])
{

    // Starts routes processing
    Ucs_Rm_Start(ucs_inst_ptr, &routes_list[0], routes_list_size);

    // ...

    if (mic2_btn_pressed)
    {
        App_SetRouteId2_OnOff(true);
    }
    else
    {
        App_SetRouteId2_OnOff(false);
    }
}