rcl  master
C API providing common ROS client library functionality.
Macros | Functions
validate_topic_name.h File Reference
#include "rcl/macros.h"
#include "rcl/types.h"
#include "rcl/visibility_control.h"

Go to the source code of this file.

Macros

#define RCL_TOPIC_NAME_VALID   0
 
#define RCL_TOPIC_NAME_INVALID_IS_EMPTY_STRING   1
 
#define RCL_TOPIC_NAME_INVALID_ENDS_WITH_FORWARD_SLASH   2
 
#define RCL_TOPIC_NAME_INVALID_CONTAINS_UNALLOWED_CHARACTERS   3
 
#define RCL_TOPIC_NAME_INVALID_NAME_TOKEN_STARTS_WITH_NUMBER   4
 
#define RCL_TOPIC_NAME_INVALID_UNMATCHED_CURLY_BRACE   5
 
#define RCL_TOPIC_NAME_INVALID_MISPLACED_TILDE   6
 
#define RCL_TOPIC_NAME_INVALID_TILDE_NOT_FOLLOWED_BY_FORWARD_SLASH   7
 
#define RCL_TOPIC_NAME_INVALID_SUBSTITUTION_CONTAINS_UNALLOWED_CHARACTERS   8
 
#define RCL_TOPIC_NAME_INVALID_SUBSTITUTION_STARTS_WITH_NUMBER   9
 

Functions

rcl_ret_t rcl_validate_topic_name (const char *topic_name, int *validation_result, size_t *invalid_index)
 Validate a given topic name. More...
 
rcl_ret_t rcl_validate_topic_name_with_size (const char *topic_name, size_t topic_name_length, int *validation_result, size_t *invalid_index)
 Validate a given topic name. More...
 
const char * rcl_topic_name_validation_result_string (int validation_result)
 Return a validation result description, or NULL if unknown or RCL_TOPIC_NAME_VALID. More...
 

Macro Definition Documentation

◆ RCL_TOPIC_NAME_VALID

#define RCL_TOPIC_NAME_VALID   0

◆ RCL_TOPIC_NAME_INVALID_IS_EMPTY_STRING

#define RCL_TOPIC_NAME_INVALID_IS_EMPTY_STRING   1

◆ RCL_TOPIC_NAME_INVALID_ENDS_WITH_FORWARD_SLASH

#define RCL_TOPIC_NAME_INVALID_ENDS_WITH_FORWARD_SLASH   2

◆ RCL_TOPIC_NAME_INVALID_CONTAINS_UNALLOWED_CHARACTERS

#define RCL_TOPIC_NAME_INVALID_CONTAINS_UNALLOWED_CHARACTERS   3

◆ RCL_TOPIC_NAME_INVALID_NAME_TOKEN_STARTS_WITH_NUMBER

#define RCL_TOPIC_NAME_INVALID_NAME_TOKEN_STARTS_WITH_NUMBER   4

◆ RCL_TOPIC_NAME_INVALID_UNMATCHED_CURLY_BRACE

#define RCL_TOPIC_NAME_INVALID_UNMATCHED_CURLY_BRACE   5

◆ RCL_TOPIC_NAME_INVALID_MISPLACED_TILDE

#define RCL_TOPIC_NAME_INVALID_MISPLACED_TILDE   6

◆ RCL_TOPIC_NAME_INVALID_TILDE_NOT_FOLLOWED_BY_FORWARD_SLASH

#define RCL_TOPIC_NAME_INVALID_TILDE_NOT_FOLLOWED_BY_FORWARD_SLASH   7

◆ RCL_TOPIC_NAME_INVALID_SUBSTITUTION_CONTAINS_UNALLOWED_CHARACTERS

#define RCL_TOPIC_NAME_INVALID_SUBSTITUTION_CONTAINS_UNALLOWED_CHARACTERS   8

◆ RCL_TOPIC_NAME_INVALID_SUBSTITUTION_STARTS_WITH_NUMBER

#define RCL_TOPIC_NAME_INVALID_SUBSTITUTION_STARTS_WITH_NUMBER   9

Function Documentation

◆ rcl_validate_topic_name()

rcl_ret_t rcl_validate_topic_name ( const char *  topic_name,
int *  validation_result,
size_t *  invalid_index 
)

Validate a given topic name.

The topic name does not need to be a full qualified name, but it should follow some of the rules in this document:

http://design.ros2.org/articles/topic_and_service_names.html

Note that this function expects any URL suffixes as described in the above document to have already been removed.

If the input topic is valid, RCL_TOPIC_NAME_VALID will be stored into validation_result. If the input topic violates any of the rules then one of these values will be stored into validation_result:

  • RCL_TOPIC_NAME_INVALID_IS_EMPTY_STRING
  • RCL_TOPIC_NAME_INVALID_ENDS_WITH_FORWARD_SLASH
  • RCL_TOPIC_NAME_INVALID_CONTAINS_UNALLOWED_CHARACTERS
  • RCL_TOPIC_NAME_INVALID_NAME_TOKEN_STARTS_WITH_NUMBER
  • RCL_TOPIC_NAME_INVALID_UNMATCHED_CURLY_BRACE
  • RCL_TOPIC_NAME_INVALID_MISPLACED_TILDE
  • RCL_TOPIC_NAME_INVALID_TILDE_NOT_FOLLOWED_BY_FORWARD_SLASH
  • RCL_TOPIC_NAME_INVALID_SUBSTITUTION_CONTAINS_UNALLOWED_CHARACTERS
  • RCL_TOPIC_NAME_INVALID_SUBSTITUTION_STARTS_WITH_NUMBER

Some checks, like the check for illegal repeated forward slashes, are not checked in this function because they would need to be checked again after expansion anyways. The purpose of this subset of checks is to try to catch issues with content that will be expanded in some way by rcl_expand_topic_name(), like ~ or substitutions inside of {}, or with other issues that would obviously prevent expansion, like RCL_TOPIC_NAME_INVALID_IS_EMPTY_STRING.

This function does not check that the substitutions are known substitutions, only that the contents of the {} follow the rules outline in the document which was linked to above.

Stricter validation can be done with rmw_validate_full_topic_name() after using rcl_expand_topic_name().

Additionally, if the invalid_index argument is not NULL, then it will be assigned the index in the topic_name string where the violation occurs. The invalid_index is not set if the validation passes.

Parameters
[in]topic_namethe topic name to be validated, must be null terminated
[out]validation_resultthe reason for validation failure, if any
[out]invalid_indexindex of violation if the input topic is invalid
Returns
RCL_RET_OK if the topic name was expanded successfully, or
RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCL_RET_ERROR if an unspecified error occurs.

◆ rcl_validate_topic_name_with_size()

rcl_ret_t rcl_validate_topic_name_with_size ( const char *  topic_name,
size_t  topic_name_length,
int *  validation_result,
size_t *  invalid_index 
)

Validate a given topic name.

This is an overload with an extra parameter for the length of topic_name.

Parameters
[in]topic_name_lengthThe number of characters in topic_name.
See also
rcl_validate_topic_name(const char *, int *, size_t *)

◆ rcl_topic_name_validation_result_string()

const char* rcl_topic_name_validation_result_string ( int  validation_result)

Return a validation result description, or NULL if unknown or RCL_TOPIC_NAME_VALID.