Function rcl_remap_topic_name

Function Documentation

rcl_ret_t rcl_remap_topic_name(const rcl_arguments_t *local_arguments, const rcl_arguments_t *global_arguments, const char *topic_name, const char *node_name, const char *node_namespace, rcl_allocator_t allocator, char **output_name)

Remap a topic name based on given rules.

The supplied topic name must have already been expanded to a fully qualified name.

If

local_arguments is not NULL and not zero intialized then its remap rules are checked first. If no rules matched and global_arguments is not NULL and not zero intitialized then its rules are checked next. If both local_arguments and global_arguments are NULL or zero intialized then the function will return RCL_RET_INVALID_ARGUMENT.

See also

rcl_expand_topic_name()

global_arguments is usually the arguments passed to rcl_init()

.

Remap rules are checked in the order they were given. For rules passed to

rcl_init()

this usually is the order they were passed on the command line.

Only the first remap rule that matches is used to remap a name. For example, if the command line arguments are

foo:=bar bar:=baz the topic foo is remapped to bar and not baz.

See also

rcl_init()

See also

rcl_get_global_arguments()

See also

rcl_parse_arguments()

node_name and node_namespace are used to expand the match and replacement into fully qualified names. Given node_name trudy, namespace /ns, and rule foo:=~/bar the names in the rule are expanded to /ns/foo:=/ns/trudy/bar. The rule will only apply if the given topic name is /ns/foo.

node_name is also used to match against node specific rules. Given rules alice:foo:=bar foo:=baz, node name alice, and topic foo the remapped topic name will be bar. If given the node name bob and topic foo the remaped topic name would be baz instead. Note that processing always stops at the first matching rule even if there is a more specific one later on. Given foo:=bar alice:foo:=baz and topic name foo the remapped topic name will always be bar regardless of the node name given.

Attribute

Adherence

Allocates Memory

Yes

Thread-Safe

No

Uses Atomics

No

Lock-Free

Yes

Parameters:

  • local_arguments – [in] Command line arguments to be used before global arguments, or if NULL or zero-initialized then only global arguments are used.

  • global_arguments – [in] Command line arguments to use if no local rules matched, or NULL or zero-initialized to ignore global arguments.

  • topic_name – [in] A fully qualified and expanded topic name to be remapped.

  • node_name – [in] The name of the node to which name belongs.

  • node_namespace – [in] The namespace of a node to which name belongs.

  • allocator – [in] A valid allocator to use.

  • output_name – [out] Either an allocated string with the remapped name, or NULL if no remap rules matched the name.

Returns:

RCL_RET_OK if the topic name was remapped or no rules matched, or

Returns:

RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or

Returns:

RCL_RET_BAD_ALLOC if allocating memory failed, or

Returns:

RCL_RET_TOPIC_NAME_INVALID if the given topic name is invalid, or

Returns:

RCL_RET_ERROR if an unspecified error occurs.