Function rcl_client_init

Function Documentation

rcl_ret_t rcl_client_init(rcl_client_t *client, const rcl_node_t *node, const rosidl_service_type_support_t *type_support, const char *service_name, const rcl_client_options_t *options)

Initialize a rcl client.

After calling this function on a rcl_client_t, it can be used to send requests of the given type by calling rcl_send_request(). If the request is received by a (possibly remote) service and if the service sends a response, the client can access the response through rcl_take_response() once the response is available to the client.

The given rcl_node_t must be valid and the resulting rcl_client_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_typesupport_cpp/service_type_support.hpp>
#include <example_interfaces/srv/add_two_ints.hpp>

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 client 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_client_t client = rcl_get_zero_initialized_client();
rcl_client_options_t client_ops = rcl_client_get_default_options();
ret = rcl_client_init(&client, &node, ts, "add_two_ints", &client_ops);
// ... error handling, and on shutdown do finalization:
ret = rcl_client_fini(&client, &node);
// ... error handling for rcl_client_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:

  • client – [inout] preallocated rcl_client_t structure

  • node – [in] valid rcl_node_t

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

  • service_name – [in] the name of the service to request

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

Returns:

RCL_RET_OK if the client was initialized successfully, or

Returns:

RCL_RET_NODE_INVALID if the node is invalid, or

Returns:

RCL_RET_ALREADY_INIT if the client is already initialized, or

Returns:

RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or

Returns:

RCL_RET_BAD_ALLOC if allocating memory fails, or

Returns:

RCL_RET_SERVICE_NAME_INVALID if the given service name is invalid, or

Returns:

RCL_RET_ERROR if an unspecified error occurs.