Function rcl_get_node_names

Function Documentation

rcl_ret_t rcl_get_node_names(const rcl_node_t *node, rcl_allocator_t allocator, rcutils_string_array_t *node_names, rcutils_string_array_t *node_namespaces)

Return a list of available nodes in the ROS graph.

The node parameter must point to a valid node.

The node_names parameter must be allocated and zero initialized. node_names is the output for this function, and contains allocated memory. Use rcutils_get_zero_initialized_string_array() for initializing an empty rcutils_string_array_t struct. This node_names struct should therefore be passed to rcutils_string_array_fini() when it is no longer needed. Failing to do so will result in leaked memory.

Example:

rcutils_string_array_t node_names =
  rcutils_get_zero_initialized_string_array();
rcl_ret_t ret = rcl_get_node_names(node, &node_names);
if (ret != RCL_RET_OK) {
  // ... error handling
}
// ... use the node_names struct, and when done:
rcutils_ret_t rcutils_ret = rcutils_string_array_fini(&node_names);
if (rcutils_ret != RCUTILS_RET_OK) {
  // ... error handling
}

Attribute

Adherence

Allocates Memory

Yes

Thread-Safe

No

Uses Atomics

No

Lock-Free

Maybe [1]

[1] implementation may need to protect the data structure with a lock

Parameters:

  • node – [in] the handle to the node being used to query the ROS graph

  • allocator – [in] used to control allocation and deallocation of names

  • node_names – [out] struct storing discovered node names

  • node_namespaces – [out] struct storing discovered node namespaces

Returns:

RCL_RET_OK if the query was successful, or

Returns:

RCL_RET_BAD_ALLOC if an error occurred while allocating memory, or

Returns:

RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or

Returns:

RCL_RET_NODE_INVALID_NAME if a node with an invalid name is detected, or

Returns:

RCL_RET_NODE_INVALID_NAMESPACE if a node with an invalid namespace is detected, or

Returns:

RCL_RET_ERROR if an unspecified error occurs.