#include "rosidl_runtime_c/service_type_support_struct.h"
#include "rcl/event_callback.h"
#include "rcl/macros.h"
#include "rcl/node.h"
#include "rcl/visibility_control.h"

Include dependency graph for client.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	rcl_client_s
	Structure which encapsulates a ROS Client. More...

struct	rcl_client_options_s
	Options available for a rcl_client_t. More...

Typedefs
typedef struct rcl_client_impl_s	rcl_client_impl_t
	Internal rcl client implementation struct.

typedef struct rcl_client_s	rcl_client_t
	Structure which encapsulates a ROS Client.

typedef struct rcl_client_options_s	rcl_client_options_t
	Options available for a rcl_client_t.

Functions
RCL_PUBLIC RCL_WARN_UNUSED rcl_client_t	rcl_get_zero_initialized_client (void)
	Return a rcl_client_t struct with members set to `NULL`. More...

RCL_PUBLIC RCL_WARN_UNUSED 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. More...

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t	rcl_client_fini (rcl_client_t client, rcl_node_t node)
	Finalize a rcl_client_t. More...

RCL_PUBLIC RCL_WARN_UNUSED rcl_client_options_t	rcl_client_get_default_options (void)
	Return the default client options in a rcl_client_options_t. More...

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t	rcl_send_request (const rcl_client_t client, const void ros_request, int64_t *sequence_number)
	Send a ROS request using a client. More...

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t	rcl_take_response_with_info (const rcl_client_t client, rmw_service_info_t request_header, void *ros_response)
	Take a ROS response using a client. More...

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t	rcl_take_response (const rcl_client_t client, rmw_request_id_t request_header, void *ros_response)
	backwards compatibility function that takes a rmw_request_id_t only

RCL_PUBLIC RCL_WARN_UNUSED const char *	rcl_client_get_service_name (const rcl_client_t *client)
	Get the name of the service that this client will request a response from. More...

RCL_PUBLIC RCL_WARN_UNUSED const rcl_client_options_t *	rcl_client_get_options (const rcl_client_t *client)
	Return the rcl client options. More...

RCL_PUBLIC RCL_WARN_UNUSED rmw_client_t *	rcl_client_get_rmw_handle (const rcl_client_t *client)
	Return the rmw client handle. More...

RCL_PUBLIC bool	rcl_client_is_valid (const rcl_client_t *client)
	Check that the client is valid. More...

RCL_PUBLIC RCL_WARN_UNUSED const rmw_qos_profile_t *	rcl_client_request_publisher_get_actual_qos (const rcl_client_t *client)
	Get the actual qos settings of the client's request publisher. More...

RCL_PUBLIC RCL_WARN_UNUSED const rmw_qos_profile_t *	rcl_client_response_subscription_get_actual_qos (const rcl_client_t *client)
	Get the actual qos settings of the client's response subscription. More...

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t	rcl_client_set_on_new_response_callback (const rcl_client_t client, rcl_event_callback_t callback, const void user_data)
	Set the on new response callback function for the client. More...

Function Documentation

◆ rcl_client_fini()

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_client_fini	(	rcl_client_t *	client,
		rcl_node_t *	node
	)

Finalize a rcl_client_t.

After calling this function, calls to rcl_send_request() and rcl_take_response() will fail when using this client. However, the given node handle is still valid.

Attribute	Adherence
Allocates Memory	Yes
Thread-Safe	No
Uses Atomics	No
Lock-Free	Yes

Parameters

[in,out]	client	handle to the client to be finalized
[in]	node	a valid (not finalized) handle to the node used to create the client

Returns: RCL_RET_OK if client was finalized successfully, or; RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or; RCL_RET_NODE_INVALID if the node is invalid, or; RCL_RET_ERROR if an unspecified error occurs.

Definition at line 168 of file client.c.

References rcl_client_options_s::allocator, rcl_client_s::impl, rcl_node_get_rmw_handle(), rcl_node_is_valid_except_context(), RCL_RET_ERROR, RCL_RET_INVALID_ARGUMENT, RCL_RET_NODE_INVALID, and RCL_RET_OK.

Here is the call graph for this function:

◆ rcl_client_get_default_options()

RCL_PUBLIC RCL_WARN_UNUSED rcl_client_options_t rcl_client_get_default_options ( void )

Return the default client options in a rcl_client_options_t.

The defaults are:

qos = rmw_qos_profile_services_default
allocator = rcl_get_default_allocator()

Definition at line 199 of file client.c.

References rcl_client_options_s::allocator, rcl_client_options_s::qos, and rcl_get_default_allocator.

Referenced by rclcpp::AsyncParametersClient::AsyncParametersClient(), and rclcpp::create_client().

Here is the caller graph for this function:

◆ rcl_client_get_options()

RCL_PUBLIC RCL_WARN_UNUSED const rcl_client_options_t* rcl_client_get_options ( const rcl_client_t * client )

Return the rcl client options.

This function returns the client's internal options struct. This function can fail, and therefore return NULL, if the:

client is NULL
client is invalid (never called init, called fini, or invalid node)

The returned struct is only valid as long as the rcl_client_t is valid. The values in the struct may change if the options of the client change, and therefore copying the struct is recommended if this is a concern.

Attribute	Adherence
Allocates Memory	Yes
Thread-Safe	No
Uses Atomics	No
Lock-Free	Yes

Parameters

[in] client pointer to the client

Returns: options struct if successful, otherwise NULL

Definition at line 221 of file client.c.

References rcl_client_is_valid().

Here is the call graph for this function:

◆ rcl_client_get_rmw_handle()

RCL_PUBLIC RCL_WARN_UNUSED rmw_client_t* rcl_client_get_rmw_handle ( const rcl_client_t * client )

Return the rmw client handle.

The handle returned is a pointer to the internally held rmw handle. This function can fail, and therefore return NULL, if the:

client is NULL
client is invalid (never called init, called fini, or invalid node)

The returned handle is made invalid if the client is finalized or if rcl_shutdown() is called. The returned handle is not guaranteed to be valid for the life time of the client as it may be finalized and recreated itself. Therefore it is recommended to get the handle from the client using this function each time it is needed and avoid use of the handle concurrently with functions that might change it.

Attribute	Adherence
Allocates Memory	Yes
Thread-Safe	No
Uses Atomics	No
Lock-Free	Yes

Parameters

[in] client pointer to the rcl client

Returns: rmw client handle if successful, otherwise NULL

Definition at line 230 of file client.c.

References rcl_client_s::impl, and rcl_client_is_valid().

Referenced by rcl_service_server_is_available().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rcl_client_get_service_name()

RCL_PUBLIC RCL_WARN_UNUSED const char* rcl_client_get_service_name ( const rcl_client_t * client )

Get the name of the service that this client will request a response from.

This function returns the client's internal service name string. This function can fail, and therefore return NULL, if the:

client is NULL
client is invalid (never called init, called fini, or invalid node)

The returned string is only valid as long as the rcl_client_t is valid. The value of the string may change if the service name changes, and therefore copying the string is recommended if this is a concern.

Attribute	Adherence
Allocates Memory	Yes
Thread-Safe	No
Uses Atomics	No
Lock-Free	Yes

Parameters

[in] client pointer to the client

Returns: name string if successful, otherwise NULL

Definition at line 210 of file client.c.

References rcl_client_s::impl, and rcl_client_is_valid().

Referenced by rclcpp::ClientBase::get_service_name().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rcl_client_init()

RCL_PUBLIC RCL_WARN_UNUSED 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:

See also: rcl_expand_topic_name

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.

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

[in,out]	client	preallocated rcl_client_t structure
[in]	node	valid rcl_node_t
[in]	type_support	type support object for the service's type
[in]	service_name	the name of the service to request
[in]	options	client options, including quality of service settings

Returns: RCL_RET_OK if the client was initialized successfully, or; RCL_RET_NODE_INVALID if the node is invalid, or; RCL_RET_ALREADY_INIT if the client is already initialized, or; RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or; RCL_RET_BAD_ALLOC if allocating memory fails, or; RCL_RET_SERVICE_NAME_INVALID if the given service name is invalid, or; RCL_RET_ERROR if an unspecified error occurs.

Definition at line 53 of file client.c.

References rcl_client_options_s::allocator, rcl_client_s::impl, rcl_client_options_s::qos, RCL_CHECK_ALLOCATOR_WITH_MSG, rcl_node_get_rmw_handle(), rcl_node_is_valid(), rcl_node_resolve_name(), RCL_RET_ALREADY_INIT, RCL_RET_BAD_ALLOC, RCL_RET_ERROR, RCL_RET_INVALID_ARGUMENT, RCL_RET_NODE_INVALID, RCL_RET_OK, RCL_RET_SERVICE_NAME_INVALID, and RCL_RET_UNKNOWN_SUBSTITUTION.

Referenced by rclcpp::Client< ServiceT >::Client().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rcl_client_is_valid()

RCL_PUBLIC bool rcl_client_is_valid ( const rcl_client_t * client )

Check that the client is valid.

The bool returned is false if client is invalid. The bool returned is true otherwise. In the case where false is to be returned, an error message is set. This function cannot fail.

Attribute	Adherence
Allocates Memory	No
Thread-Safe	No
Uses Atomics	No
Lock-Free	Yes

Parameters

[in] client pointer to the rcl client

Returns: true if client is valid, otherwise false

Definition at line 303 of file client.c.

References rcl_client_s::impl.

Referenced by rcl_client_get_options(), rcl_client_get_rmw_handle(), rcl_client_get_service_name(), rcl_client_request_publisher_get_actual_qos(), rcl_client_response_subscription_get_actual_qos(), rcl_client_set_on_new_response_callback(), rcl_send_request(), and rcl_take_response_with_info().

Here is the caller graph for this function:

◆ rcl_client_request_publisher_get_actual_qos()

RCL_PUBLIC RCL_WARN_UNUSED const rmw_qos_profile_t* rcl_client_request_publisher_get_actual_qos ( const rcl_client_t * client )

Get the actual qos settings of the client's request publisher.

Used to get the actual qos settings of the client's request publisher. The actual configuration applied when using RMW_*_SYSTEM_DEFAULT can only be resolved after the creation of the client, and it depends on the underlying rmw implementation. If the underlying setting in use can't be represented in ROS terms, it will be set to RMW_*_UNKNOWN. The returned struct is only valid as long as the rcl_client_t is valid.

Attribute	Adherence
Allocates Memory	No
Thread-Safe	Yes
Uses Atomics	No
Lock-Free	Yes

Parameters

[in] client pointer to the rcl client

Returns: qos struct if successful, otherwise NULL

Definition at line 314 of file client.c.

References rcl_client_s::impl, and rcl_client_is_valid().

Referenced by rclcpp::ClientBase::get_request_publisher_actual_qos().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rcl_client_response_subscription_get_actual_qos()

RCL_PUBLIC RCL_WARN_UNUSED const rmw_qos_profile_t* rcl_client_response_subscription_get_actual_qos ( const rcl_client_t * client )

Get the actual qos settings of the client's response subscription.

Used to get the actual qos settings of the client's response subscription. The actual configuration applied when using RMW_*_SYSTEM_DEFAULT can only be resolved after the creation of the client, and it depends on the underlying rmw implementation. If the underlying setting in use can't be represented in ROS terms, it will be set to RMW_*_UNKNOWN. The returned struct is only valid as long as the rcl_client_t is valid.

Attribute	Adherence
Allocates Memory	No
Thread-Safe	Yes
Uses Atomics	No
Lock-Free	Yes

Parameters

[in] client pointer to the rcl client

Returns: qos struct if successful, otherwise NULL

Definition at line 323 of file client.c.

References rcl_client_s::impl, and rcl_client_is_valid().

Referenced by rclcpp::ClientBase::get_response_subscription_actual_qos().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rcl_client_set_on_new_response_callback()

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_client_set_on_new_response_callback	(	const rcl_client_t *	client,
		rcl_event_callback_t	callback,
		const void *	user_data
	)

Set the on new response callback function for the client.

This API sets the callback function to be called whenever the client is notified about a new response.

See also: rmw_client_set_on_new_response_callback for details about this function.

Attribute	Adherence
Allocates Memory	No
Thread-Safe	Yes
Uses Atomics	Maybe [1]
Lock-Free	Maybe [1]

[1] rmw implementation defined

Parameters

[in]	client	The client on which to set the callback
[in]	callback	The callback to be called when new responses arrive, may be NULL
[in]	user_data	Given to the callback when called later, may be NULL

Returns: RCL_RET_OK if callback was set to the listener, or; RCL_RET_INVALID_ARGUMENT if client is NULL, or; RCL_RET_UNSUPPORTED if the API is not implemented in the dds implementation

Definition at line 332 of file client.c.

References rcl_client_s::impl, rcl_client_is_valid(), and RCL_RET_INVALID_ARGUMENT.

Here is the call graph for this function:

◆ rcl_get_zero_initialized_client()

RCL_PUBLIC RCL_WARN_UNUSED rcl_client_t rcl_get_zero_initialized_client ( void )

Return a rcl_client_t struct with members set to NULL.

Should be called to get a null rcl_client_t before passing to rcl_client_init().

Definition at line 46 of file client.c.

◆ rcl_send_request()

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_send_request	(	const rcl_client_t *	client,
		const void *	ros_request,
		int64_t *	sequence_number
	)

Send a ROS request using a client.

It is the job of the caller to ensure that the type of the ros_request parameter and the type associate with the client (via the type support) match. Passing a different type to send_request produces undefined behavior and cannot be checked by this function and therefore no deliberate error will occur.

rcl_send_request() is an non-blocking call.

The ROS request message given by the ros_request void pointer is always owned by the calling code, but should remain constant during send_request.

This function is thread safe so long as access to both the client and the ros_request is synchronized. That means that calling rcl_send_request() from multiple threads is allowed, but calling rcl_send_request() at the same time as non-thread safe client functions is not, e.g. calling rcl_send_request() and rcl_client_fini() concurrently is not allowed. Before calling rcl_send_request() the message can change and after calling rcl_send_request() the message can change, but it cannot be changed during the send_request call. The same ros_request, however, can be passed to multiple calls of rcl_send_request() simultaneously, even if the clients differ. The ros_request is unmodified by rcl_send_request().

Attribute	Adherence
Allocates Memory	No
Thread-Safe	Yes [1]
Uses Atomics	No
Lock-Free	Yes

[1] for unique pairs of clients and requests, see above for more

Parameters

[in]	client	handle to the client which will make the response
[in]	ros_request	type-erased pointer to the ROS request message
[out]	sequence_number	the sequence number

Returns: RCL_RET_OK if the request was sent successfully, or; RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or; RCL_RET_CLIENT_INVALID if the client is invalid, or; RCL_RET_ERROR if an unspecified error occurs.

Definition at line 239 of file client.c.

References rcl_client_s::impl, rcl_client_is_valid(), RCL_RET_CLIENT_INVALID, RCL_RET_ERROR, RCL_RET_INVALID_ARGUMENT, and RCL_RET_OK.

Here is the call graph for this function:

◆ rcl_take_response_with_info()

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_take_response_with_info	(	const rcl_client_t *	client,
		rmw_service_info_t *	request_header,
		void *	ros_response
	)

Take a ROS response using a client.

It is the job of the caller to ensure that the type of the ros_response parameter and the type associate with the client (via the type support) match. Passing a different type to take_response produces undefined behavior and cannot be checked by this function and therefore no deliberate error will occur. The request_header is an rmw struct for meta-information about the request sent (e.g. the sequence number). The caller must provide a pointer to an allocated struct. This function will populate the struct's fields. ros_response should point to an already allocated ROS response message struct of the correct type, into which the response from the service will be copied.

Attribute	Adherence
Allocates Memory	Maybe [1]
Thread-Safe	No
Uses Atomics	No
Lock-Free	Yes

[1] only if required when filling the message, avoided for fixed sizes

Parameters

[in]	client	handle to the client which will take the response
[in,out]	request_header	pointer to the request header
[in,out]	ros_response	type-erased pointer to the ROS response message

Returns: RCL_RET_OK if the response was taken successfully, or; RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or; RCL_RET_CLIENT_INVALID if the client is invalid, or; RCL_RET_CLIENT_TAKE_FAILED if take failed but no error occurred in the middleware, or; RCL_RET_ERROR if an unspecified error occurs.

Definition at line 259 of file client.c.

References rcl_client_s::impl, rcl_client_is_valid(), RCL_RET_CLIENT_INVALID, RCL_RET_CLIENT_TAKE_FAILED, RCL_RET_ERROR, RCL_RET_INVALID_ARGUMENT, and RCL_RET_OK.

Referenced by rcl_take_response().

Here is the call graph for this function:

Here is the caller graph for this function:

Classes

Typedefs

Functions

Function Documentation

◆ rcl_client_fini()

◆ rcl_client_get_default_options()

◆ rcl_client_get_options()

◆ rcl_client_get_rmw_handle()

◆ rcl_client_get_service_name()

◆ rcl_client_init()

◆ rcl_client_is_valid()

◆ rcl_client_request_publisher_get_actual_qos()

◆ rcl_client_response_subscription_get_actual_qos()

◆ rcl_client_set_on_new_response_callback()

◆ rcl_get_zero_initialized_client()

◆ rcl_send_request()

◆ rcl_take_response_with_info()