#include "rosidl_generator_c/message_type_support_struct.h"
#include "rcl/macros.h"
#include "rcl/node.h"
#include "rcl/visibility_control.h"

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

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

Typedefs
typedef struct rcl_subscription_t	rcl_subscription_t
	Structure which encapsulates a ROS Subscription. More...

typedef struct rcl_subscription_options_t	rcl_subscription_options_t
	Options available for a rcl subscription. More...

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

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_ret_t	rcl_subscription_fini (rcl_subscription_t subscription, rcl_node_t node)
	Finalize a rcl_subscription_t. More...

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

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

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

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

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

Typedef Documentation

§ rcl_subscription_t

typedef struct rcl_subscription_t rcl_subscription_t

Structure which encapsulates a ROS Subscription.

§ rcl_subscription_options_t

typedef struct rcl_subscription_options_t rcl_subscription_options_t

Options available for a rcl subscription.

Function Documentation

§ rcl_get_zero_initialized_subscription()

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().

§ rcl_subscription_init()

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_generator_c/message_type_support.h>
#include <std_msgs/msgs/string.h>
rosidl_message_type_support_t * string_ts =
  ROSIDL_GET_MESSAGE_TYPE_SUPPORT(std_msgs, String);

For C++ a template function is used:

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

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

Todo:: TODO(wjwwood) update this once we've come up with an official scheme. The topic name must be a non-empty string which follows the topic naming format.

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_generator_c/message_type_support.h>
#include <std_msgs/msgs/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", &node_ops);
// ... error handling
rosidl_message_type_support_t * ts = ROSIDL_GET_MESSAGE_TYPE_SUPPORT(std_msgs, 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_BAD_ALLOC if allocating memory failed, or; RCL_RET_ERROR if an unspecified error occurs.

§ rcl_subscription_fini()

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	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_ERROR if an unspecified error occurs.

§ rcl_subscription_get_default_options()

rcl_subscription_options_t rcl_subscription_get_default_options ( void )

Return the default subscription options in a rcl_subscription_options_t.

The defaults are:

ignore_local_publications = false
qos = rmw_qos_profile_default
allocator = rcl_get_default_allocator()

§ rcl_take()

rcl_ret_t rcl_take	(	const rcl_subscription_t *	subscription,
		void *	ros_message,
		rmw_message_info_t *	message_info
	)

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 associate 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.

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

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.

§ rcl_subscription_get_topic_name()

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

§ rcl_subscription_get_options()

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

§ rcl_subscription_get_rmw_handle()

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

Classes

Typedefs

Functions

Typedef Documentation

§ rcl_subscription_t

§ rcl_subscription_options_t

Function Documentation

§ rcl_get_zero_initialized_subscription()

§ rcl_subscription_init()

§ rcl_subscription_fini()

§ rcl_subscription_get_default_options()

§ rcl_take()

§ rcl_subscription_get_topic_name()

§ rcl_subscription_get_options()

§ rcl_subscription_get_rmw_handle()