rcl  master
C API providing common ROS client library functionality.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Functions
expand_topic_name.h File Reference
#include "rcutils/types/string_map.h"
#include "rcl/allocator.h"
#include "rcl/macros.h"
#include "rcl/types.h"
#include "rcl/visibility_control.h"

Go to the source code of this file.

Functions

rcl_ret_t rcl_expand_topic_name (const char *input_topic_name, const char *node_name, const char *node_namespace, const rcutils_string_map_t *substitutions, rcl_allocator_t allocator, char **output_topic_name)
 Expand a given topic name into a fully-qualified topic name. More...
 
rcl_ret_t rcl_get_default_topic_name_substitutions (rcutils_string_map_t *string_map)
 Fill a given string map with the default substitution pairs. More...
 

Function Documentation

◆ rcl_expand_topic_name()

rcl_ret_t rcl_expand_topic_name ( const char *  input_topic_name,
const char *  node_name,
const char *  node_namespace,
const rcutils_string_map_t substitutions,
rcl_allocator_t  allocator,
char **  output_topic_name 
)

Expand a given topic name into a fully-qualified topic name.

The input_topic_name, node_name, and node_namespace arguments must all be vaid, null terminated c strings. The output_topic_name will not be assigned a value in the event of an error.

The output_topic_name will be null terminated. It is also allocated, so it needs to be deallocated, when it is no longer needed, with the same allocator given to this function. Make sure the char * which is passed for the output_topic_name does not point to allocated memory before calling this function, because it will be overwritten and therefore leaked if this function is successful.

Expected usage:

rcutils_ret_t rcutils_ret = rcutils_string_map_init(&substitutions_map, 0, rcutils_allocator);
if (rcutils_ret != RCUTILS_RET_OK) {
// ... error handling
}
if (ret != RCL_RET_OK) {
// ... error handling
}
char * expanded_topic_name = NULL;
"some/topic",
"my_node",
"my_ns",
&substitutions_map,
allocator,
&expanded_topic_name);
if (ret != RCL_RET_OK) {
// ... error handling
} else {
RCUTILS_LOG_INFO("Expanded topic name: %s", expanded_topic_name)
// ... when done the output topic name needs to be deallocated:
allocator.deallocate(expanded_topic_name, allocator.state);
}

The input topic name is validated using rcl_validate_topic_name(), but if it fails validation RCL_RET_TOPIC_NAME_INVALID is returned.

The input node name is validated using rmw_validate_node_name(), but if it fails validation RCL_RET_NODE_INVALID_NAME is returned.

The input node namespace is validated using rmw_validate_namespace(), but if it fails validation RCL_RET_NODE_INVALID_NAMESPACE is returned.

In addition to what is given by rcl_get_default_topic_name_substitutions(), there are there these substitutions:

  • {node} -> the name of the node
  • {namespace} -> the namespace of the node
  • {ns} -> the namespace of the node

If an unknown substitution is used, RCL_RET_UNKNOWN_SUBSTITUTION is returned.


Attribute Adherence
Allocates Memory Yes
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in]input_topic_nametopic name to be expanded
[in]node_namename of the node associated with the topic
[in]node_namespacenamespace of the node associated with the topic
[in]substitutionsstring map with possible substitutions
[in]allocatorthe allocator to be used when creating the output topic
[out]output_topic_nameoutput char * pointer
Returns
RCL_RET_OK if the topic name was expanded successfully, or
RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCL_RET_BAD_ALLOC if allocating memory failed, or
RCL_RET_TOPIC_NAME_INVALID if the given topic name is invalid, or
RCL_RET_NODE_INVALID_NAME if the name is invalid, or
RCL_RET_NODE_INVALID_NAMESPACE if the namespace_ is invalid, or
RCL_RET_UNKNOWN_SUBSTITUTION for unknown substitutions in name, or
RCL_RET_ERROR if an unspecified error occurs.

◆ rcl_get_default_topic_name_substitutions()

rcl_ret_t rcl_get_default_topic_name_substitutions ( rcutils_string_map_t string_map)

Fill a given string map with the default substitution pairs.

If the string map is not initialized RCL_RET_INVALID_ARGUMENT is returned.

Parameters
[in,out]string_maprcutils_string_map_t map to be filled with pairs
Returns
RCL_RET_OK if successfully, or
RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCL_RET_BAD_ALLOC if allocating memory failed, or
RCL_RET_ERROR if an unspecified error occurs.