Function rcl_action_client_init

Function Documentation

rcl_ret_t rcl_action_client_init(rcl_action_client_t *action_client, rcl_node_t *node, const rosidl_action_type_support_t *type_support, const char *action_name, const rcl_action_client_options_t *options)

Initialize a rcl_action_client_t.

After calling this function on a rcl_action_client_t, it can be used to send goals of the given type to the given topic using rcl_action_send_goal_request(). If a goal request is sent to a (possibly remote) server and if the server sends a response, the client can access the response with rcl_take_goal_response() once the response is available.

After a goal request has been accepted, the rcl_action_client_t associated with the goal can perform the following operations:

  • Send a request for the result with rcl_action_send_result_request(). If the server sends a response when the goal terminates, the result can be accessed with rcl_action_take_result_response(), once the response is available.

  • Send a cancel request for the goal with rcl_action_send_cancel_request(). If the server sends a response to a cancel request, the client can access the response with rcl_action_take_cancel_response() once the response is available.

  • Take feedback about the goal with rcl_action_take_feedback().

A rcl_action_client_t can be used to access the current status of all accepted goals communicated by the action server with rcl_action_take_status().

The given rcl_node_t must be valid and the resulting rcl_action_client_t is only valid as long as the given rcl_node_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 client name string.

See also

rcl_expand_topic_name

Expected usage (for C action clients):

#include <rcl/rcl.h>
#include <rcl_action/action_client.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_client_t action_client = rcl_action_get_zero_initialized_client();
rcl_action_client_options_t action_client_ops = rcl_action_client_get_default_options();
ret = rcl_action_client_init(&action_client, &node, ts, "fibonacci", &action_client_ops);
// ... error handling, and on shutdown do finalization:
ret = rcl_action_client_fini(&action_client, &node);
// ... error handling for rcl_action_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:

  • action_client – [out] a preallocated, zero-initialized action client structure to be initialized

  • node – [in] valid rcl node handle

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

  • action_name – [in] the name of the action

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

Returns:

RCL_RET_OK if action_client 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_ALREADY_INIT if the action client is already initialized, 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.