#include "rosidl_runtime_c/message_type_support_struct.h"
#include "rcl/event_callback.h"
#include "rcl/macros.h"
#include "rcl/node.h"
#include "rcl/visibility_control.h"
#include "rmw/dynamic_message_type_support.h"
#include "rmw/message_sequence.h"

Include dependency graph for subscription.h:

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

Go to the source code of this file.

Classes
struct	rcl_subscription_s
	Structure which encapsulates a ROS Subscription. More...

struct	rcl_subscription_options_s
	Options available for a rcl subscription. More...

struct	rcl_subscription_content_filter_options_s

Typedefs
typedef struct rcl_subscription_impl_s	rcl_subscription_impl_t
	Internal rcl implementation struct.

typedef struct rcl_subscription_s	rcl_subscription_t
	Structure which encapsulates a ROS Subscription.

typedef struct rcl_subscription_options_s	rcl_subscription_options_t
	Options available for a rcl subscription.

typedef struct rcl_subscription_content_filter_options_s	rcl_subscription_content_filter_options_t

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

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t	rcl_subscription_init (rcl_subscription_t subscription, const rcl_node_t node, const rosidl_message_type_support_t type_support, const char topic_name, const rcl_subscription_options_t *options)
	Initialize a ROS subscription. More...

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t	rcl_subscription_fini (rcl_subscription_t subscription, rcl_node_t node)
	Finalize a rcl_subscription_t. More...

RCL_PUBLIC RCL_WARN_UNUSED rcl_subscription_options_t	rcl_subscription_get_default_options (void)
	Return the default subscription options in a rcl_subscription_options_t. More...

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t	rcl_subscription_options_fini (rcl_subscription_options_t *option)
	Reclaim resources held inside rcl_subscription_options_t structure. More...

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t	rcl_subscription_options_set_content_filter_options (const char filter_expression, size_t expression_parameters_argc, const char expression_parameter_argv[], rcl_subscription_options_t *options)
	Set the content filter options for the given subscription options. More...

RCL_PUBLIC RCL_WARN_UNUSED rcl_subscription_content_filter_options_t	rcl_get_zero_initialized_subscription_content_filter_options (void)
	Return the zero initialized subscription content filter options.

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t	rcl_subscription_content_filter_options_init (const rcl_subscription_t subscription, const char filter_expression, size_t expression_parameters_argc, const char expression_parameter_argv[], rcl_subscription_content_filter_options_t options)
	Initialize the content filter options for the given subscription options. More...

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t	rcl_subscription_content_filter_options_set (const rcl_subscription_t subscription, const char filter_expression, size_t expression_parameters_argc, const char expression_parameter_argv[], rcl_subscription_content_filter_options_t options)
	Set the content filter options for the given subscription options. More...

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t	rcl_subscription_content_filter_options_fini (const rcl_subscription_t subscription, rcl_subscription_content_filter_options_t options)
	Reclaim rcl_subscription_content_filter_options_t structure. More...

RCL_PUBLIC RCL_WARN_UNUSED bool	rcl_subscription_is_cft_enabled (const rcl_subscription_t *subscription)
	Check if the content filtered topic feature is enabled in the subscription. More...

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t	rcl_subscription_set_content_filter (const rcl_subscription_t subscription, const rcl_subscription_content_filter_options_t options)
	Set the filter expression and expression parameters for the subscription. More...

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t	rcl_subscription_get_content_filter (const rcl_subscription_t subscription, rcl_subscription_content_filter_options_t options)
	Retrieve the filter expression of the subscription. More...

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t	rcl_take (const rcl_subscription_t subscription, void ros_message, rmw_message_info_t message_info, rmw_subscription_allocation_t allocation)
	Take a ROS message from a topic using a rcl subscription. More...

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t	rcl_take_sequence (const rcl_subscription_t subscription, size_t count, rmw_message_sequence_t message_sequence, rmw_message_info_sequence_t message_info_sequence, rmw_subscription_allocation_t allocation)
	Take a sequence of messages from a topic using a rcl subscription. More...

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t	rcl_take_serialized_message (const rcl_subscription_t subscription, rcl_serialized_message_t serialized_message, rmw_message_info_t message_info, rmw_subscription_allocation_t allocation)
	Take a serialized raw message from a topic using a rcl subscription. More...

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t	rcl_take_dynamic_message (const rcl_subscription_t subscription, rosidl_dynamic_typesupport_dynamic_data_t dynamic_message, rmw_message_info_t message_info, rmw_subscription_allocation_t allocation)
	Take a dynamic type message from a topic using a rcl subscription. More...

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t	rcl_take_loaned_message (const rcl_subscription_t subscription, void loaned_message, rmw_message_info_t message_info, rmw_subscription_allocation_t *allocation)
	Take a loaned message from a topic using a rcl subscription. More...

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t	rcl_return_loaned_message_from_subscription (const rcl_subscription_t subscription, void loaned_message)
	Return a loaned message from a topic using a rcl subscription. More...

RCL_PUBLIC RCL_WARN_UNUSED const char *	rcl_subscription_get_topic_name (const rcl_subscription_t *subscription)
	Get the topic name for the subscription. More...

RCL_PUBLIC RCL_WARN_UNUSED const rcl_subscription_options_t *	rcl_subscription_get_options (const rcl_subscription_t *subscription)
	Return the rcl subscription options. More...

RCL_PUBLIC RCL_WARN_UNUSED rmw_subscription_t *	rcl_subscription_get_rmw_handle (const rcl_subscription_t *subscription)
	Return the rmw subscription handle. More...

RCL_PUBLIC bool	rcl_subscription_is_valid (const rcl_subscription_t *subscription)
	Check that the subscription is valid. More...

RCL_PUBLIC RCL_WARN_UNUSED rmw_ret_t	rcl_subscription_get_publisher_count (const rcl_subscription_t subscription, size_t publisher_count)
	Get the number of publishers matched to a subscription. More...

RCL_PUBLIC RCL_WARN_UNUSED const rmw_qos_profile_t *	rcl_subscription_get_actual_qos (const rcl_subscription_t *subscription)
	Get the actual qos settings of the subscription. More...

RCL_PUBLIC bool	rcl_subscription_can_loan_messages (const rcl_subscription_t *subscription)
	Check if subscription instance can loan messages. More...

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t	rcl_subscription_set_on_new_message_callback (const rcl_subscription_t subscription, rcl_event_callback_t callback, const void user_data)
	Set the on new message callback function for the subscription. More...

Function Documentation

◆ rcl_get_zero_initialized_subscription()

RCL_PUBLIC RCL_WARN_UNUSED rcl_subscription_t rcl_get_zero_initialized_subscription ( void )

Return a rcl_subscription_t struct with members set to NULL.

Should be called to get a null rcl_subscription_t before passing to rcl_subscription_init().

Definition at line 43 of file subscription.c.

Referenced by rclcpp::SubscriptionBase::SubscriptionBase().

Here is the caller graph for this function:

◆ rcl_return_loaned_message_from_subscription()

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_return_loaned_message_from_subscription	(	const rcl_subscription_t *	subscription,
		void *	loaned_message
	)

Return a loaned message from a topic using a rcl subscription.

If a loaned message was previously obtained from the middleware with a call to

See also: rcl_take_loaned_message, this message has to be returned to indicate to the middleware that the user no longer needs that memory. The user must not delete the message.

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

Parameters

[in]	subscription	the handle to the subscription from which to take
[in]	loaned_message	a pointer to the loaned messages.

Returns: RCL_RET_OK if the message was published, or; RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or; RCL_RET_SUBSCRIPTION_INVALID if the subscription is invalid, or; RCL_RET_UNSUPPORTED if the middleware does not support that feature, or; RCL_RET_ERROR if an unspecified error occurs.

Definition at line 725 of file subscription.c.

References rcl_subscription_s::impl, RCL_RET_INVALID_ARGUMENT, RCL_RET_SUBSCRIPTION_INVALID, and rcl_subscription_is_valid().

Here is the call graph for this function:

◆ rcl_subscription_can_loan_messages()

RCL_PUBLIC bool rcl_subscription_can_loan_messages ( const rcl_subscription_t * subscription )

Check if subscription instance can loan messages.

Depending on the middleware and the message type, this will return true if the middleware can allocate a ROS message instance.

Parameters

[in] subscription The subscription instance to check for the ability to loan messages

Returns: true if the subscription instance can loan messages, false otherwise.

Definition at line 809 of file subscription.c.

References rcl_subscription_options_s::disable_loaned_message, rcl_subscription_s::impl, and rcl_subscription_is_valid().

Referenced by rclcpp::SubscriptionBase::can_loan_messages().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rcl_subscription_content_filter_options_fini()

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_subscription_content_filter_options_fini	(	const rcl_subscription_t *	subscription,
		rcl_subscription_content_filter_options_t *	options
	)

Reclaim rcl_subscription_content_filter_options_t structure.

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

Parameters

[in]	subscription	the handle to the subscription.
[in]	options	The structure which its resources have to be deallocated.

Returns: RCL_RET_OK if the memory was successfully freed, or; RCL_RET_SUBSCRIPTION_INVALID if subscription is invalid, or; RCL_RET_INVALID_ARGUMENT if option is NULL, or if its allocator is invalid and the structure contains initialized memory.

Definition at line 455 of file subscription.c.

References rcl_subscription_options_s::allocator, rcl_subscription_s::impl, RCL_CHECK_ALLOCATOR_WITH_MSG, RCL_RET_INVALID_ARGUMENT, RCL_RET_SUBSCRIPTION_INVALID, and rcl_subscription_is_valid().

Referenced by rclcpp::SubscriptionBase::get_content_filter(), and rclcpp::SubscriptionBase::set_content_filter().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rcl_subscription_content_filter_options_init()

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_subscription_content_filter_options_init	(	const rcl_subscription_t *	subscription,
		const char *	filter_expression,
		size_t	expression_parameters_argc,
		const char *	expression_parameter_argv[],
		rcl_subscription_content_filter_options_t *	options
	)

Initialize the content filter options for the given subscription options.

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

Parameters

[in]	subscription	the handle to the subscription.
[in]	filter_expression	The filter expression is similar to the WHERE part of an SQL clause, use empty ("") can reset (or clear) the content filter setting of a subscription.
[in]	expression_parameters_argc	The maximum of expression parameters argc is 100.
[in]	expression_parameter_argv	The expression parameters argv are the tokens placeholder ‘parameters’ (i.e., "%n" tokens begin from 0) in the filter_expression.

It can be NULL if there is no "%n" tokens placeholder in filter_expression.

Parameters

[out] options The subscription options to be set.

Returns: RCL_RET_OK if set options successfully, or; RCL_RET_SUBSCRIPTION_INVALID if subscription is invalid, or; RCL_RET_INVALID_ARGUMENT if arguments invalid, or; RCL_RET_BAD_ALLOC if allocating memory fails.

Definition at line 396 of file subscription.c.

References rcl_subscription_options_s::allocator, rcl_subscription_s::impl, RCL_CHECK_ALLOCATOR_WITH_MSG, RCL_RET_INVALID_ARGUMENT, RCL_RET_SUBSCRIPTION_INVALID, and rcl_subscription_is_valid().

Referenced by rclcpp::SubscriptionBase::set_content_filter().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rcl_subscription_content_filter_options_set()

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_subscription_content_filter_options_set	(	const rcl_subscription_t *	subscription,
		const char *	filter_expression,
		size_t	expression_parameters_argc,
		const char *	expression_parameter_argv[],
		rcl_subscription_content_filter_options_t *	options
	)

Set the content filter options for the given subscription options.

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

Parameters

[in]	subscription	the handle to the subscription.
[in]	filter_expression	The filter expression is similar to the WHERE part of an SQL clause, use empty ("") can reset (or clear) the content filter setting of a subscription.
[in]	expression_parameters_argc	The maximum of expression parameters argc is 100.
[in]	expression_parameter_argv	The expression parameters argv are the tokens placeholder ‘parameters’ (i.e., "%n" tokens begin from 0) in the filter_expression.

It can be NULL if there is no "%n" tokens placeholder in filter_expression.

Parameters

[out] options The subscription options to be set.

Returns: RCL_RET_OK if set options successfully, or; RCL_RET_SUBSCRIPTION_INVALID if subscription is invalid, or; RCL_RET_INVALID_ARGUMENT if arguments invalid, or; RCL_RET_BAD_ALLOC if allocating memory fails.

Definition at line 426 of file subscription.c.

References rcl_subscription_options_s::allocator, rcl_subscription_s::impl, RCL_CHECK_ALLOCATOR_WITH_MSG, RCL_RET_INVALID_ARGUMENT, RCL_RET_SUBSCRIPTION_INVALID, and rcl_subscription_is_valid().

Here is the call graph for this function:

◆ rcl_subscription_fini()

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_subscription_fini	(	rcl_subscription_t *	subscription,
		rcl_node_t *	node
	)

Finalize a rcl_subscription_t.

After calling, the node will no longer be subscribed on this topic (assuming this is the only subscription on this topic in this node).

After calling, calls to rcl_wait and rcl_take will fail when using this subscription. Additioanlly rcl_wait will be interrupted if currently blocking. 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]	subscription	handle to the subscription to be deinitialized
[in]	node	a valid (not finalized) handle to the node used to create the subscription

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

Definition at line 180 of file subscription.c.

References rcl_subscription_options_s::allocator, rcl_subscription_s::impl, rcl_node_get_rmw_handle(), rcl_node_is_valid_except_context(), RCL_RET_ERROR, RCL_RET_INVALID_ARGUMENT, RCL_RET_NODE_INVALID, RCL_RET_OK, RCL_RET_SUBSCRIPTION_INVALID, and rcl_subscription_options_fini().

Referenced by rclcpp::SubscriptionBase::SubscriptionBase().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rcl_subscription_get_actual_qos()

RCL_PUBLIC RCL_WARN_UNUSED const rmw_qos_profile_t* rcl_subscription_get_actual_qos ( const rcl_subscription_t * subscription )

Get the actual qos settings of the subscription.

Used to get the actual qos settings of the subscription. The actual configuration applied when using RMW_*_SYSTEM_DEFAULT can only be resolved after the creation of the subscription, 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_subscription_t is valid.

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

Parameters

[in] subscription pointer to the rcl subscription

Returns: qos struct if successful, otherwise NULL

Definition at line 800 of file subscription.c.

References rcl_subscription_s::impl, and rcl_subscription_is_valid().

Referenced by rclcpp::SubscriptionBase::get_actual_qos().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rcl_subscription_get_content_filter()

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_subscription_get_content_filter	(	const rcl_subscription_t *	subscription,
		rcl_subscription_content_filter_options_t *	options
	)

Retrieve the filter expression of the subscription.

This function will return an filter expression by the given subscription.

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

Parameters

[in]	subscription	The subscription object to inspect.
[out]	options	The rcl content filter options. It is up to the caller to finalize this options later on, using rcl_subscription_content_filter_options_fini().

Returns: RCL_RET_OK if the query was successful, or; RCL_RET_INVALID_ARGUMENT if subscription is NULL, or; RCL_RET_INVALID_ARGUMENT if options is NULL, or; RCL_RET_BAD_ALLOC if memory allocation fails, or; RCL_RET_UNSUPPORTED if the implementation does not support content filter topic, or; RCL_RET_ERROR if an unspecified error occurs.

Definition at line 518 of file subscription.c.

References rcl_subscription_options_s::allocator, rcl_subscription_s::impl, RCL_CHECK_ALLOCATOR_WITH_MSG, RCL_RET_INVALID_ARGUMENT, RCL_RET_SUBSCRIPTION_INVALID, and rcl_subscription_is_valid().

Referenced by rclcpp::SubscriptionBase::get_content_filter().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rcl_subscription_get_default_options()

RCL_PUBLIC RCL_WARN_UNUSED rcl_subscription_options_t rcl_subscription_get_default_options ( void )

Return the default subscription options in a rcl_subscription_options_t.

The defaults are:

qos = rmw_qos_profile_default
allocator = rcl_get_default_allocator()
rmw_subscription_options = rmw_get_default_subscription_options();
disable_loaned_message = true, false only if ROS_DISABLE_LOANED_MESSAGES=0

Returns: A structure containing the default options for a subscription.

Definition at line 229 of file subscription.c.

References rcl_subscription_options_s::allocator, rcl_subscription_options_s::disable_loaned_message, rcl_subscription_options_s::qos, rcl_get_default_allocator, and rcl_subscription_options_s::rmw_subscription_options.

Referenced by rclcpp::SubscriptionOptionsWithAllocator< Allocator >::to_rcl_subscription_options().

Here is the caller graph for this function:

◆ rcl_subscription_get_options()

RCL_PUBLIC RCL_WARN_UNUSED const rcl_subscription_options_t* rcl_subscription_get_options ( const rcl_subscription_t * subscription )

Return the rcl subscription options.

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

subscription is NULL
subscription is invalid (never called init, called fini, or invalid)

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

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

Parameters

[in] subscription pointer to the subscription

Returns: options struct if successful, otherwise NULL

Definition at line 749 of file subscription.c.

References rcl_subscription_s::impl, and rcl_subscription_is_valid().

Here is the call graph for this function:

◆ rcl_subscription_get_publisher_count()

RCL_PUBLIC RCL_WARN_UNUSED rmw_ret_t rcl_subscription_get_publisher_count	(	const rcl_subscription_t *	subscription,
		size_t *	publisher_count
	)

Get the number of publishers matched to a subscription.

Used to get the internal count of publishers matched to a subscription.

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

[1] only if the underlying rmw doesn't make use of this feature

Parameters

[in]	subscription	pointer to the rcl subscription
[out]	publisher_count	number of matched publishers

Returns: RCL_RET_OK if the count was retrieved, or; RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or; RCL_RET_SUBSCRIPTION_INVALID if the subscription is invalid, or; RCL_RET_ERROR if an unspecified error occurs.

Definition at line 778 of file subscription.c.

References rcl_subscription_s::impl, RCL_RET_INVALID_ARGUMENT, RCL_RET_OK, RCL_RET_SUBSCRIPTION_INVALID, and rcl_subscription_is_valid().

Referenced by rclcpp::SubscriptionBase::get_publisher_count().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rcl_subscription_get_rmw_handle()

RCL_PUBLIC RCL_WARN_UNUSED rmw_subscription_t* rcl_subscription_get_rmw_handle ( const rcl_subscription_t * subscription )

Return the rmw subscription handle.

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

subscription is NULL
subscription is invalid (never called init, called fini, or invalid)

The returned handle is made invalid if the subscription is finalized or if rcl_shutdown() is called. The returned handle is not guaranteed to be valid for the life time of the subscription as it may be finalized and recreated itself. Therefore it is recommended to get the handle from the subscription 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	No
Thread-Safe	No
Uses Atomics	No
Lock-Free	Yes

Parameters

[in] subscription pointer to the rcl subscription

Returns: rmw subscription handle if successful, otherwise NULL

Definition at line 758 of file subscription.c.

References rcl_subscription_s::impl, and rcl_subscription_is_valid().

Here is the call graph for this function:

◆ rcl_subscription_get_topic_name()

RCL_PUBLIC RCL_WARN_UNUSED const char* rcl_subscription_get_topic_name ( const rcl_subscription_t * subscription )

Get the topic name for the subscription.

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

subscription is NULL
subscription is invalid (never called init, called fini, or invalid)

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

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

Parameters

[in] subscription the pointer to the subscription

Returns: name string if successful, otherwise NULL

Definition at line 740 of file subscription.c.

References rcl_subscription_s::impl, and rcl_subscription_is_valid().

Referenced by rclcpp::SubscriptionBase::get_topic_name().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rcl_subscription_init()

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_subscription_init	(	rcl_subscription_t *	subscription,
		const rcl_node_t *	node,
		const rosidl_message_type_support_t *	type_support,
		const char *	topic_name,
		const rcl_subscription_options_t *	options
	)

Initialize a ROS subscription.

After calling this function on a rcl_subscription_t, it can be used to take messages of the given type to the given topic using rcl_take().

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

The rosidl_message_type_support_t is obtained on a per .msg type basis. When the user defines a ROS message, code is generated which provides the required rosidl_message_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 std_msgs/String):

#include <rosidl_runtime_c/message_type_support_struct.h>
#include <std_msgs/msg/string.h>
const rosidl_message_type_support_t * string_ts =
  ROSIDL_GET_MSG_TYPE_SUPPORT(std_msgs, msg, String);

For C++ a template function is used:

#include <rosidl_typesupport_cpp/message_type_support.hpp>
#include <std_msgs/msg/string.hpp>
using rosidl_typesupport_cpp::get_message_type_support_handle;
const rosidl_message_type_support_t * string_ts =
  get_message_type_support_handle<std_msgs::msg::String>();

The rosidl_message_type_support_t object contains message type specific information used to subscribe to messages.

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 (de)initializing the subscription to allocate space for incidental things, e.g. the topic name string.

Expected usage (for C messages):

#include <rcl/rcl.h>
#include <rosidl_runtime_c/message_type_support_struct.h>
#include <std_msgs/msg/string.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_message_type_support_t * ts =
  ROSIDL_GET_MSG_TYPE_SUPPORT(std_msgs, msg, String);
rcl_subscription_t subscription = rcl_get_zero_initialized_subscription();
rcl_subscription_options_t subscription_ops = rcl_subscription_get_default_options();
ret = rcl_subscription_init(&subscription, &node, ts, "chatter", &subscription_ops);
// ... error handling, and when finished deinitialization
ret = rcl_subscription_fini(&subscription, &node);
// ... error handling for rcl_subscription_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

[out]	subscription	preallocated subscription structure
[in]	node	valid rcl node handle
[in]	type_support	type support object for the topic's type
[in]	topic_name	the name of the topic
[in]	options	subscription options, including quality of service settings

Returns: RCL_RET_OK if subscription was initialized successfully, or; RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or; RCL_RET_ALREADY_INIT if the subcription is already initialized, or; RCL_RET_NODE_INVALID if the node is invalid, or; RCL_RET_BAD_ALLOC if allocating memory failed, or; RCL_RET_TOPIC_NAME_INVALID if the given topic name is invalid, or; RCL_RET_ERROR if an unspecified error occurs.

Definition at line 51 of file subscription.c.

References rcl_subscription_options_s::allocator, rcl_subscription_s::impl, rcl_subscription_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_TOPIC_NAME_INVALID, RCL_RET_UNKNOWN_SUBSTITUTION, rcl_subscription_options_fini(), and rcl_subscription_options_s::rmw_subscription_options.

Referenced by rclcpp::SubscriptionBase::SubscriptionBase().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rcl_subscription_is_cft_enabled()

RCL_PUBLIC RCL_WARN_UNUSED bool rcl_subscription_is_cft_enabled ( const rcl_subscription_t * subscription )

Check if the content filtered topic feature is enabled in the subscription.

Depending on the middleware and whether cft is enabled in the subscription.

Returns: true if the content filtered topic of subscription is enabled, otherwise false

Definition at line 475 of file subscription.c.

References rcl_subscription_s::impl, and rcl_subscription_is_valid().

Referenced by rclcpp::SubscriptionBase::is_cft_enabled().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rcl_subscription_is_valid()

RCL_PUBLIC bool rcl_subscription_is_valid ( const rcl_subscription_t * subscription )

Check that the subscription is valid.

The bool returned is false if subscription 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] subscription pointer to the rcl subscription

Returns: true if subscription is valid, otherwise false

Definition at line 767 of file subscription.c.

References rcl_subscription_s::impl.

Here is the caller graph for this function:

◆ rcl_subscription_options_fini()

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_subscription_options_fini ( rcl_subscription_options_t * option )

Reclaim resources held inside rcl_subscription_options_t structure.

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

Parameters

[in] option The structure which its resources have to be deallocated.

Returns: RCL_RET_OK if the memory was successfully freed, or; RCL_RET_INVALID_ARGUMENT if option is NULL, or; RCL_RET_BAD_ALLOC if deallocating memory fails.

Definition at line 258 of file subscription.c.

References rcl_subscription_options_s::allocator, RCL_CHECK_ALLOCATOR_WITH_MSG, RCL_RET_INVALID_ARGUMENT, RCL_RET_OK, and rcl_subscription_options_s::rmw_subscription_options.

Referenced by rcl_subscription_fini(), and rcl_subscription_init().

Here is the caller graph for this function:

◆ rcl_subscription_options_set_content_filter_options()

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_subscription_options_set_content_filter_options	(	const char *	filter_expression,
		size_t	expression_parameters_argc,
		const char *	expression_parameter_argv[],
		rcl_subscription_options_t *	options
	)

Set the content filter options for the given subscription options.

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

Parameters

[in]	filter_expression	The filter expression is similar to the WHERE part of an SQL clause.
[in]	expression_parameters_argc	The maximum of expression parameters argc is 100.
[in]	expression_parameter_argv	The expression parameters argv are the tokens placeholder ‘parameters’ (i.e., "%n" tokens begin from 0) in the filter_expression.

It can be NULL if there is no "%n" tokens placeholder in filter_expression.

Parameters

[out] options The subscription options to be set.

Returns: RCL_RET_OK if set options successfully, or; RCL_RET_INVALID_ARGUMENT if arguments invalid, or; RCL_RET_BAD_ALLOC if allocating memory fails.

Definition at line 280 of file subscription.c.

References rcl_subscription_options_s::allocator, RCL_CHECK_ALLOCATOR_WITH_MSG, RCL_RET_BAD_ALLOC, RCL_RET_INVALID_ARGUMENT, and rcl_subscription_options_s::rmw_subscription_options.

Referenced by rcl_subscription_set_content_filter(), and rclcpp::SubscriptionOptionsWithAllocator< Allocator >::to_rcl_subscription_options().

Here is the caller graph for this function:

◆ rcl_subscription_set_content_filter()

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_subscription_set_content_filter	(	const rcl_subscription_t *	subscription,
		const rcl_subscription_content_filter_options_t *	options
	)

Set the filter expression and expression parameters for the subscription.

This function will set a filter expression and an array of expression parameters for the given subscription.

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

Parameters

[in]	subscription	The subscription to set content filter options.
[in]	options	The rcl content filter options.

Returns: RCL_RET_OK if the query was successful, or; RCL_RET_INVALID_ARGUMENT if subscription is NULL, or; RCL_RET_INVALID_ARGUMENT if options is NULL, or; RCL_RET_UNSUPPORTED if the implementation does not support content filter topic, or; RCL_RET_ERROR if an unspecified error occurs.

Definition at line 484 of file subscription.c.

References rcl_subscription_s::impl, RCL_RET_INVALID_ARGUMENT, RCL_RET_SUBSCRIPTION_INVALID, rcl_subscription_is_valid(), and rcl_subscription_options_set_content_filter_options().

Referenced by rclcpp::SubscriptionBase::set_content_filter().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rcl_subscription_set_on_new_message_callback()

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_subscription_set_on_new_message_callback	(	const rcl_subscription_t *	subscription,
		rcl_event_callback_t	callback,
		const void *	user_data
	)

Set the on new message callback function for the subscription.

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

See also: rmw_subscription_set_on_new_message_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]	subscription	The subscription on which to set the callback
[in]	callback	The callback to be called when new messages arrive, may be NULL
[in]	user_data	Given to the callback when called later, may be NULL

Returns: RCL_RET_OK if successful, or; RCL_RET_INVALID_ARGUMENT if subscription is NULL, or; RCL_RET_UNSUPPORTED if the API is not implemented in the dds implementation

Definition at line 823 of file subscription.c.

References rcl_subscription_s::impl, RCL_RET_INVALID_ARGUMENT, and rcl_subscription_is_valid().

Here is the call graph for this function:

◆ rcl_take()

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_take	(	const rcl_subscription_t *	subscription,
		void *	ros_message,
		rmw_message_info_t *	message_info,
		rmw_subscription_allocation_t *	allocation
	)

Take a ROS message from a topic using a rcl subscription.

It is the job of the caller to ensure that the type of the ros_message argument and the type associated with the subscription, via the type support, match. Passing a different type to rcl_take produces undefined behavior and cannot be checked by this function and therefore no deliberate error will occur.

TODO(wjwwood) blocking of take? TODO(wjwwood) pre-, during-, and post-conditions for message ownership? TODO(wjwwood) is rcl_take thread-safe? TODO(wjwwood) Should there be an rcl_message_info_t?

The ros_message pointer should point to an already allocated ROS message struct of the correct type, into which the taken ROS message will be copied if one is available. If taken is false after calling, then the ROS message will be unmodified.

The taken boolean may be false even if a wait set reports that the subscription was ready to be taken from in some cases, e.g. when the state of the subscription changes it may cause the wait set to wake up but subsequent takes to fail to take anything.

If allocation is required when taking the message, e.g. if space needs to be allocated for a dynamically sized array in the target message, then the allocator given in the subscription options is used.

The rmw_message_info struct contains meta information about this particular message instance, like what the GUID of the publisher which published it originally or whether or not the message received from within the same process. The message_info argument should be an already allocated rmw_message_info_t structure. Passing NULL for message_info will result in the argument being ignored.

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]	subscription	the handle to the subscription from which to take
[in,out]	ros_message	type-erased ptr to a allocated ROS message
[out]	message_info	rmw struct which contains meta-data for the message
[in]	allocation	structure pointer used for memory preallocation (may be NULL)

Returns: RCL_RET_OK if the message was taken, or; RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or; RCL_RET_SUBSCRIPTION_INVALID if the subscription is invalid, or; RCL_RET_BAD_ALLOC if allocating memory failed, or; RCL_RET_SUBSCRIPTION_TAKE_FAILED if take failed but no error occurred in the middleware, or; RCL_RET_ERROR if an unspecified error occurs.

Definition at line 542 of file subscription.c.

References rcl_subscription_s::impl, RCL_RET_INVALID_ARGUMENT, RCL_RET_OK, RCL_RET_SUBSCRIPTION_INVALID, RCL_RET_SUBSCRIPTION_TAKE_FAILED, and rcl_subscription_is_valid().

Referenced by rcl_take_serialized_message(), and rclcpp::SubscriptionBase::take_type_erased().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rcl_take_dynamic_message()

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_take_dynamic_message	(	const rcl_subscription_t *	subscription,
		rosidl_dynamic_typesupport_dynamic_data_t *	dynamic_message,
		rmw_message_info_t *	message_info,
		rmw_subscription_allocation_t *	allocation
	)

Take a dynamic type message from a topic using a rcl subscription.

In contrast to rcl_take(), this function takes a dynamic type message with dynamic data taken directly from the middleware. It is the job of the caller to ensure that the type associated with the subscription matches, and that the subscription uses the dynamic type rosidl_message_type_support_t.

Apart from the differences above, this function behaves like rcl_take().

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

Parameters

[in]	subscription	the handle to the subscription from which to take
[in,out]	dynamic_message	pointer to a (pre-allocated) dynamic type message.
[out]	message_info	rmw struct which contains meta-data for the message
[in]	allocation	structure pointer used for memory preallocation (may be NULL)

Returns: RCL_RET_OK if the message was taken, or; RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or; RCL_RET_SUBSCRIPTION_INVALID if the subscription is invalid, or; RCL_RET_BAD_ALLOC if allocating memory failed, or; RCL_RET_SUBSCRIPTION_TAKE_FAILED if take failed but no error occurred in the middleware, or; RCL_RET_ERROR if an unspecified error occurs.

Definition at line 657 of file subscription.c.

References rcl_subscription_s::impl, RCL_RET_INVALID_ARGUMENT, RCL_RET_OK, RCL_RET_SUBSCRIPTION_INVALID, RCL_RET_SUBSCRIPTION_TAKE_FAILED, and rcl_subscription_is_valid().

Here is the call graph for this function:

◆ rcl_take_loaned_message()

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_take_loaned_message	(	const rcl_subscription_t *	subscription,
		void **	loaned_message,
		rmw_message_info_t *	message_info,
		rmw_subscription_allocation_t *	allocation
	)

Take a loaned message from a topic using a rcl subscription.

Depending on the middleware, incoming messages can be loaned to the user's callback without further copying. The implicit contract here is that the middleware owns the memory allocated for this message. The user must not destroy the message, but rather has to return it with a call to

See also: rcl_return_loaned_message to the middleware.

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

Parameters

[in]	subscription	the handle to the subscription from which to take
[in,out]	loaned_message	a pointer to the loaned messages.
[out]	message_info	rmw struct which contains meta-data for the message.
[in]	allocation	structure pointer used for memory preallocation (may be NULL)

Returns: RCL_RET_OK if the loaned message sequence was taken, or; RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or; RCL_RET_SUBSCRIPTION_INVALID if the subscription is invalid, or; RCL_RET_BAD_ALLOC if allocating memory failed, or; RCL_RET_SUBSCRIPTION_TAKE_FAILED if take failed but no error occurred in the middleware, or; RCL_RET_UNSUPPORTED if the middleware does not support that feature, or; RCL_RET_ERROR if an unspecified error occurs.

Definition at line 689 of file subscription.c.

References rcl_subscription_s::impl, RCL_RET_INVALID_ARGUMENT, RCL_RET_OK, RCL_RET_SUBSCRIPTION_INVALID, RCL_RET_SUBSCRIPTION_TAKE_FAILED, and rcl_subscription_is_valid().

Here is the call graph for this function:

◆ rcl_take_sequence()

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_take_sequence	(	const rcl_subscription_t *	subscription,
		size_t	count,
		rmw_message_sequence_t *	message_sequence,
		rmw_message_info_sequence_t *	message_info_sequence,
		rmw_subscription_allocation_t *	allocation
	)

Take a sequence of messages from a topic using a rcl subscription.

In contrast to rcl_take(), this function can take multiple messages at the same time. It is the job of the caller to ensure that the type of the message_sequence argument and the type associated with the subscription, via the type support, match.

The message_sequence pointer should point to an already allocated sequence of ROS messages of the correct type, into which the taken ROS messages will be copied if messages are available. The message_sequence size member will be set to the number of messages correctly taken.

The rmw_message_info_sequence struct contains meta information about the corresponding message instance index. The message_info_sequence argument should be an already allocated rmw_message_info_sequence_t structure.

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

[1] only if storage in the serialized_message is insufficient

Parameters

[in]	subscription	the handle to the subscription from which to take.
[in]	count	number of messages to attempt to take.
[in,out]	message_sequence	pointer to a (pre-allocated) message sequence.
[in,out]	message_info_sequence	pointer to a (pre-allocated) message info sequence.
[in]	allocation	structure pointer used for memory preallocation (may be NULL)

Returns: RCL_RET_OK if one or more messages was taken, or; RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or; RCL_RET_SUBSCRIPTION_INVALID if the subscription is invalid, or; RCL_RET_BAD_ALLOC if allocating memory failed, or; RCL_RET_SUBSCRIPTION_TAKE_FAILED if take failed but no error occurred in the middleware, or; RCL_RET_ERROR if an unspecified error occurs.

Definition at line 577 of file subscription.c.

References rcl_subscription_s::impl, RCL_RET_INVALID_ARGUMENT, RCL_RET_OK, RCL_RET_SUBSCRIPTION_INVALID, RCL_RET_SUBSCRIPTION_TAKE_FAILED, and rcl_subscription_is_valid().

Here is the call graph for this function:

◆ rcl_take_serialized_message()

RCL_PUBLIC RCL_WARN_UNUSED rcl_ret_t rcl_take_serialized_message	(	const rcl_subscription_t *	subscription,
		rcl_serialized_message_t *	serialized_message,
		rmw_message_info_t *	message_info,
		rmw_subscription_allocation_t *	allocation
	)

Take a serialized raw message from a topic using a rcl subscription.

In contrast to rcl_take(), this function stores the taken message in its raw binary representation. It is the job of the caller to ensure that the type associate with the subscription matches, and can optionally be deserialized into its ROS message via, the correct type support. If the serialized_message parameter contains enough preallocated memory, the incoming message can be taken without any additional memory allocation. If not, the function will dynamically allocate enough memory for the message. Passing a different type to rcl_take produces undefined behavior and cannot be checked by this function and therefore no deliberate error will occur.

Apart from the differences above, this function behaves like rcl_take().

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

[1] only if storage in the serialized_message is insufficient

Parameters

[in]	subscription	the handle to the subscription from which to take
[in,out]	serialized_message	pointer to a (pre-allocated) serialized message.
[out]	message_info	rmw struct which contains meta-data for the message
[in]	allocation	structure pointer used for memory preallocation (may be NULL)

Returns: RCL_RET_OK if the message was published, or; RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or; RCL_RET_SUBSCRIPTION_INVALID if the subscription is invalid, or; RCL_RET_BAD_ALLOC if allocating memory failed, or; RCL_RET_SUBSCRIPTION_TAKE_FAILED if take failed but no error occurred in the middleware, or; RCL_RET_ERROR if an unspecified error occurs.

Definition at line 623 of file subscription.c.

References rcl_subscription_s::impl, RCL_RET_INVALID_ARGUMENT, RCL_RET_OK, RCL_RET_SUBSCRIPTION_INVALID, RCL_RET_SUBSCRIPTION_TAKE_FAILED, rcl_subscription_is_valid(), and rcl_take().

Referenced by rclcpp::SubscriptionBase::take_serialized().

Here is the call graph for this function:

Here is the caller graph for this function:

Classes

Typedefs

Functions

Function Documentation

◆ rcl_get_zero_initialized_subscription()

◆ rcl_return_loaned_message_from_subscription()

◆ rcl_subscription_can_loan_messages()

◆ rcl_subscription_content_filter_options_fini()

◆ rcl_subscription_content_filter_options_init()

◆ rcl_subscription_content_filter_options_set()

◆ rcl_subscription_fini()

◆ rcl_subscription_get_actual_qos()

◆ rcl_subscription_get_content_filter()

◆ rcl_subscription_get_default_options()

◆ rcl_subscription_get_options()

◆ rcl_subscription_get_publisher_count()

◆ rcl_subscription_get_rmw_handle()

◆ rcl_subscription_get_topic_name()

◆ rcl_subscription_init()

◆ rcl_subscription_is_cft_enabled()

◆ rcl_subscription_is_valid()

◆ rcl_subscription_options_fini()

◆ rcl_subscription_options_set_content_filter_options()

◆ rcl_subscription_set_content_filter()

◆ rcl_subscription_set_on_new_message_callback()

◆ rcl_take()

◆ rcl_take_dynamic_message()

◆ rcl_take_loaned_message()

◆ rcl_take_sequence()

◆ rcl_take_serialized_message()