Function rcl_action_server_init

Defined in File action_server.h

Function Documentation

rcl_ret_t rcl_action_server_init(rcl_action_server_t *action_server, rcl_node_t *node, rcl_clock_t *clock, const rosidl_action_type_support_t *type_support, const char *action_name, const rcl_action_server_options_t *options)

Initialize an action server.

After calling this function on a rcl_action_server_t, it can be used to take goals of the given type for the given action name using rcl_action_take_goal_request() and take cancel requests with rcl_action_take_cancel_request(). It can also send a result for a request using rcl_action_send_result() or rcl_action_send_cancel_response().

After accepting a goal with rcl_action_take_goal_request(), the action server can be used to send feedback with rcl_action_publish_feedback() and send status messages with rcl_action_publish_status().

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

The give rcl_clock_t must be valid and the resulting rcl_ction_server_t is only valid as long ast he given rcl_clock_t remains valid.

The rosidl_action_type_support_t is obtained on a per .action type basis. When the user defines a ROS action, code is generated which provides the required rosidl_action_type_support_t object. This object can be obtained using a language appropriate mechanism.

Todo:: TODO(jacobperron) write these instructions once and link to it instead

For C, a macro can be used (for example example_interfaces/Fibonacci):

#include <rosidl_runtime_c/action_type_support_struct.h>
#include <example_interfaces/action/fibonacci.h>
const rosidl_action_type_support_t * ts =
  ROSIDL_GET_ACTION_TYPE_SUPPORT(example_interfaces, Fibonacci);

For C++, a template function is used:

#include <rosidl_runtime_cpp/action_type_support.hpp>
#include <example_interfaces/action/fibonacci.h>
using rosidl_typesupport_cpp::get_action_type_support_handle;
const rosidl_action_type_support_t * ts =
  get_action_type_support_handle<example_interfaces::action::Fibonacci>();

The rosidl_action_type_support_t object contains action type specific information used to send or take goals, results, and feedback.

The topic name must be a c string that 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 that is used when initializing/finalizing the client to allocate space for incidentals, e.g. the action server name string.

See also

rcl_expand_topic_name

Expected usage (for C action servers):

#include <rcl/rcl.h>
#include <rcl_action/rcl_action.h>
#include <rosidl_runtime_c/action_type_support_struct.h>
#include <example_interfaces/action/fibonacci.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_action_type_support_t * ts =
  ROSIDL_GET_ACTION_TYPE_SUPPORT(example_interfaces, Fibonacci);
rcl_action_server_t action_server = rcl_action_get_zero_initialized_server();
rcl_action_server_options_t action_server_ops = rcl_action_server_get_default_options();
ret = rcl_action_server_init(&action_server, &node, ts, "fibonacci", &action_server_ops);
// ... error handling, and on shutdown do finalization:
ret = rcl_action_server_fini(&action_server, &node);
// ... error handling for rcl_action_server_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:

action_server – [out] handle to a preallocated, zero-initialized action server structure to be initialized.
node – [in] valid node handle
clock – [in] valid clock handle
type_support – [in] type support object for the action’s type
action_name – [in] the name of the action
options – [in] action_server options, including quality of service settings

Returns:

RCL_RET_OK if action_server was initialized successfully, or

Returns:

RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or

Returns:

RCL_RET_NODE_INVALID if the node is invalid, or

Returns:

RCL_RET_BAD_ALLOC if allocating memory failed, or

Returns:

RCL_RET_ACTION_NAME_INVALID if the given action name is invalid, or

Returns:

RCL_RET_ERROR if an unspecified error occurs.