rcl  master
C API providing common ROS client library functionality.
Classes | Typedefs | Functions
remap.h File Reference
#include "rcl/allocator.h"
#include "rcl/arguments.h"
#include "rcl/macros.h"
#include "rcl/types.h"
#include "rcl/visibility_control.h"
Include dependency graph for remap.h:

Go to the source code of this file.

Classes

struct  rcl_remap_t
 Hold remapping rules. More...
 

Typedefs

typedef struct rcl_remap_t rcl_remap_t
 Hold remapping rules.
 

Functions

rcl_remap_t rcl_get_zero_initialized_remap (void)
 Return a rcl_remap_t struct with members initialized to NULL.
 
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. More...
 
rcl_ret_t rcl_remap_service_name (const rcl_arguments_t *local_arguments, const rcl_arguments_t *global_arguments, const char *service_name, const char *node_name, const char *node_namespace, rcl_allocator_t allocator, char **output_name)
 Remap a service name based on given rules. More...
 
rcl_ret_t rcl_remap_node_name (const rcl_arguments_t *local_arguments, const rcl_arguments_t *global_arguments, const char *node_name, rcl_allocator_t allocator, char **output_name)
 Remap a node name based on given rules. More...
 
rcl_ret_t rcl_remap_node_namespace (const rcl_arguments_t *local_arguments, const rcl_arguments_t *global_arguments, const char *node_name, rcl_allocator_t allocator, char **output_namespace)
 Remap a namespace based on given rules. More...
 
rcl_ret_t rcl_remap_copy (const rcl_remap_t *rule, rcl_remap_t *rule_out)
 Copy one remap structure into another. More...
 
rcl_ret_t rcl_remap_fini (rcl_remap_t *remap)
 Reclaim resources held inside rcl_remap_t structure. More...
 

Function Documentation

◆ rcl_remap_topic_name()

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.

See also
rcl_expand_topic_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.

global_arguments is usually the arguments passed to rcl_init().

See also
rcl_init()
rcl_get_global_arguments()

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.

See also
rcl_parse_arguments()

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.

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
[in]local_argumentsCommand line arguments to be used before global arguments, or if NULL or zero-initialized then only global arguments are used.
[in]global_argumentsCommand line arguments to use if no local rules matched, or NULL or zero-initialized to ignore global arguments.
[in]topic_nameA fully qualified and expanded topic name to be remapped.
[in]node_nameThe name of the node to which name belongs.
[in]node_namespaceThe namespace of a node to which name belongs.
[in]allocatorA valid allocator to use.
[out]output_nameEither 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
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_ERROR if an unspecified error occurs.

◆ rcl_remap_service_name()

rcl_ret_t rcl_remap_service_name ( const rcl_arguments_t local_arguments,
const rcl_arguments_t global_arguments,
const char *  service_name,
const char *  node_name,
const char *  node_namespace,
rcl_allocator_t  allocator,
char **  output_name 
)

Remap a service name based on given rules.

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

The behavior of this function is identical to rcl_expand_topic_name() except that it applies to service names instead of topic names.

See also
rcl_expand_topic_name()

Attribute Adherence
Allocates Memory Yes
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in]local_argumentsCommand line arguments to be used before global arguments, or if NULL or zero-initialized then only global arguments are used.
[in]global_argumentsCommand line arguments to use if no local rules matched, or NULL or zero-initialized to ignore global arguments.
[in]service_nameA fully qualified and expanded service name to be remapped.
[in]node_nameThe name of the node to which name belongs.
[in]node_namespaceThe namespace of a node to which name belongs.
[in]allocatorA valid allocator to use.
[out]output_nameEither an allocated string with the remapped name, or NULL if no remap rules matched the name.
Returns
RCL_RET_OK if the name was remapped or no rules matched, or
RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCL_RET_BAD_ALLOC if allocating memory failed, or
RCL_RET_SERVICE_NAME_INVALID if the given name is invalid, or
RCL_RET_ERROR if an unspecified error occurs.

◆ rcl_remap_node_name()

rcl_ret_t rcl_remap_node_name ( const rcl_arguments_t local_arguments,
const rcl_arguments_t global_arguments,
const char *  node_name,
rcl_allocator_t  allocator,
char **  output_name 
)

Remap a node name based on given rules.

This function returns the node name that a node with the given name would be remapped to. When a node's name is remapped it changes its logger name and the output of expanding relative topic and service names.

When composing nodes make sure that the final node names used are unique per process. There is not currently a way to independently remap the names of two nodes that were created with the same node name and are manually composed into one process.

The behavior of local_arguments, global_arguments, node_name, the order remap rules are applied, and node specific rules is identical to rcl_remap_topic_name().

See also
rcl_remap_topic_name()

Attribute Adherence
Allocates Memory Yes
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in]local_argumentsArguments to be used before global arguments.
[in]global_argumentsCommand line arguments to use if no local rules matched, or NULL or zero-initialized to ignore global arguments.
[in]node_nameThe current name of the node.
[in]allocatorA valid allocator to use.
[out]output_nameEither an allocated string with the remapped name, or NULL if no remap rules matched the name.
Returns
RCL_RET_OK If the name was remapped or no rules matched, or
RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCL_RET_BAD_ALLOC if allocating memory failed, or
RCL_RET_NODE_INVALID_NAME if the name is invalid, or
RCL_RET_ERROR if an unspecified error occurs.

◆ rcl_remap_node_namespace()

rcl_ret_t rcl_remap_node_namespace ( const rcl_arguments_t local_arguments,
const rcl_arguments_t global_arguments,
const char *  node_name,
rcl_allocator_t  allocator,
char **  output_namespace 
)

Remap a namespace based on given rules.

This function returns the namespace that a node with the given name would be remapped to. When a node's namespace is remapped it changes its logger name and the output of expanding relative topic and service names.

The behavior of local_arguments, global_arguments, node_name, the order remap rules are applied, and node specific rules is identical to rcl_remap_topic_name().

See also
rcl_remap_topic_name()

Attribute Adherence
Allocates Memory Yes
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in]local_argumentsArguments to be used before global arguments.
[in]global_argumentsCommand line arguments to use if no local rules matched, or NULL or zero-initialized to ignore global arguments.
[in]node_nameThe name of the node whose namespace is being remapped.
[in]allocatorA valid allocator to be used.
[out]output_namespaceEither an allocated string with the remapped namespace, or NULL if no remap rules matched the name.
Returns
RCL_RET_OK if the node name was remapped or no rules matched, or
RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCL_RET_BAD_ALLOC if allocating memory failed, or
RCL_RET_NODE_INVALID_NAMESPACE if the remapped namespace is invalid, or
RCL_RET_ERROR if an unspecified error occurs.

◆ rcl_remap_copy()

rcl_ret_t rcl_remap_copy ( const rcl_remap_t rule,
rcl_remap_t rule_out 
)

Copy one remap structure into another.


Attribute Adherence
Allocates Memory Yes
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in]ruleThe structure to be copied. Its allocator is used to copy memory into the new structure.
[out]rule_outA zero-initialized rcl_remap_t structure to be copied into.
Returns
RCL_RET_OK if the structure was copied successfully, or
RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or
RCL_RET_BAD_ALLOC if allocating memory failed, or
RCL_RET_ERROR if an unspecified error occurs.

◆ rcl_remap_fini()

rcl_ret_t rcl_remap_fini ( rcl_remap_t remap)

Reclaim resources held inside rcl_remap_t structure.


Attribute Adherence
Allocates Memory No
Thread-Safe Yes
Uses Atomics No
Lock-Free Yes
Parameters
[in]remapThe structure to be deallocated.
Returns
RCL_RET_OK if the memory was successfully freed, or
RCL_RET_INVALID_ARGUMENT if any function arguments are invalid, or
RCL_RET_ERROR if an unspecified error occurs.