Function rcl_service_init

Function Documentation

rcl_ret_t rcl_service_init(rcl_service_t *service, const rcl_node_t *node, const rosidl_service_type_support_t *type_support, const char *service_name, const rcl_service_options_t *options)

Initialize a rcl service.

After calling this function on a rcl_service_t, it can be used to take requests of the given type to the given topic using rcl_take_request(). It can also send a response to a request using rcl_send_response().

The given rcl_node_t must be valid and the resulting rcl_service_t is only valid as long as the given rcl_node_t remains valid.

The rosidl_service_type_support_t is obtained on a per .srv type basis. When the user defines a ROS service, code is generated which provides the required rosidl_service_type_support_t object. This object can be obtained using a language appropriate mechanism.

Todo:

TODO(wjwwood) write these instructions once and link to it instead

For C, a macro can be used (for example example_interfaces/AddTwoInts):

#include <rosidl_runtime_c/service_type_support_struct.h>
#include <example_interfaces/srv/add_two_ints.h>
const rosidl_service_type_support_t * ts =
  ROSIDL_GET_SRV_TYPE_SUPPORT(example_interfaces, srv, AddTwoInts);

For C++, a template function is used:

#include <rosidl_runtime_cpp/service_type_support.hpp>
#include <example_interfaces/srv/add_two_ints.h>
using rosidl_typesupport_cpp::get_service_type_support_handle;
const rosidl_service_type_support_t * ts =
  get_service_type_support_handle<example_interfaces::srv::AddTwoInts>();

The rosidl_service_type_support_t object contains service type specific information used to send or take requests and responses.

The topic name must be a c string which follows the topic and service name format rules for unexpanded names, also known as non-fully qualified names:

The options struct allows the user to set the quality of service settings as well as a custom allocator which is used when initializing/finalizing the service to allocate space for incidentals, e.g. the service name string.

See also

rcl_expand_topic_name

Expected usage (for C services):

#include <rcl/rcl.h>
#include <rosidl_runtime_c/service_type_support_struct.h>
#include <example_interfaces/srv/add_two_ints.h>

rcl_node_t node = rcl_get_zero_initialized_node();
rcl_node_options_t node_ops = rcl_node_get_default_options();
rcl_ret_t ret = rcl_node_init(&node, "node_name", "/my_namespace", &node_ops);
// ... error handling
const rosidl_service_type_support_t * ts =
  ROSIDL_GET_SRV_TYPE_SUPPORT(example_interfaces, srv, AddTwoInts);
rcl_service_t service = rcl_get_zero_initialized_service();
rcl_service_options_t service_ops = rcl_service_get_default_options();
ret = rcl_service_init(&service, &node, ts, "add_two_ints", &service_ops);
// ... error handling, and on shutdown do finalization:
ret = rcl_service_fini(&service, &node);
// ... error handling for rcl_service_fini()
ret = rcl_node_fini(&node);
// ... error handling for rcl_node_fini()

Attribute

Adherence

Allocates Memory

Yes

Thread-Safe

No

Uses Atomics

No

Lock-Free

Yes

Parameters:

  • service – [out] preallocated service structure

  • node – [in] valid rcl node handle

  • type_support – [in] type support object for the service’s type

  • service_name – [in] the name of the service

  • options – [in] service options, including quality of service settings

Returns:

RCL_RET_OK if service was initialized successfully, or

Returns:

RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or

Returns:

RCL_RET_ALREADY_INIT if the service is already initialized, or

Returns:

RCL_RET_NODE_INVALID if the node is invalid, or

Returns:

RCL_RET_BAD_ALLOC if allocating memory failed, or

Returns:

RCL_RET_SERVICE_NAME_INVALID if the given service name is invalid, or

Returns:

RCL_RET_ERROR if an unspecified error occurs.