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 node names and their associated namespaces in the ROS graph.

The node parameter must point to a valid node.

The node_names and node_namespaces parameters must be allocated and zero initialized. node_names and node_namespaces are the output for this function, and contain allocated memory. Use rcutils_get_zero_initialized_string_array() for initializing an empty rcutils_string_array_t struct. These node_names and node_namespaces structs should therefore be passed to rcutils_string_array_fini() when they are 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();
rcutils_string_array_t node_namespaces =
  rcutils_get_zero_initialized_string_array();
rcl_ret_t ret = rcl_get_node_names(node, &node_names, &node_namespaces);
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
}
rcutils_ret_t rcutils_ret = rcutils_string_array_fini(&node_namespaces);
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.