Function rcl_publisher_init

Function Documentation

rcl_ret_t rcl_publisher_init(rcl_publisher_t *publisher, const rcl_node_t *node, const rosidl_message_type_support_t *type_support, const char *topic_name, const rcl_publisher_options_t *options)

Initialize a rcl publisher.

After calling this function on a rcl_publisher_t, it can be used to publish messages of the given type to the given topic using rcl_publish().

The given rcl_node_t must be valid and the resulting rcl_publisher_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>
const rosidl_message_type_support_t * string_ts =
  rosidl_typesupport_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.

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 publisher to allocate space for incidentals, e.g. the topic name string.

See also

rcl_expand_topic_name

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_publisher_t publisher = rcl_get_zero_initialized_publisher();
rcl_publisher_options_t publisher_ops = rcl_publisher_get_default_options();
ret = rcl_publisher_init(&publisher, &node, ts, "chatter", &publisher_ops);
// ... error handling, and on shutdown do finalization:
ret = rcl_publisher_fini(&publisher, &node);
// ... error handling for rcl_publisher_fini()
ret = rcl_node_fini(&node);
// ... error handling for rcl_deinitialize_node()

Attribute

Adherence

Allocates Memory

Yes

Thread-Safe

No

Uses Atomics

No

Lock-Free

Yes

Parameters:

  • publisher – [inout] preallocated publisher structure

  • node – [in] valid rcl node handle

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

  • topic_name – [in] the name of the topic to publish on

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

Returns:

RCL_RET_OK if the publisher was initialized successfully, or

Returns:

RCL_RET_NODE_INVALID if the node is invalid, or

Returns:

RCL_RET_ALREADY_INIT if the publisher 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_TOPIC_NAME_INVALID if the given topic name is invalid, or

Returns:

RCL_RET_ERROR if an unspecified error occurs.