一、本文范围

        本文指定了描述用于在组件之间交换信息的数据结构的文件格式。数据结构以与编程语言无关的方式定义。请参阅其他文章以了解与编程语言特定类型和 API 的映射。

        数据结构由一组字段定义。字段的顺序无关紧要。每个字段由类型和名称描述。

二、消息

        单个数据结构称为消息。每条消息都有一个名称。与包的名称一起，可以唯一标识一条消息。

三、服务

        对于请求/回复式通信，两个交换的数据结构是相关的。这些数据结构对称为服务 服务由其名称和所在的包标识。每个服务描述两条消息，一条用于请求数据结构，一条用于回复数据结构。

四、字段类型

        字段的类型可以是原始类型，也可以是其他数据结构。这些中的每一个都可以选择是动态或静态大小的数组。

4.1 原始字段类型，定义了以下原始类型：

• bool
• byte
• char
• float32, float64
• int8, uint8
• int16, uint16
• int32, uint32
• int64, uint64
• string

TODO:  考虑 wchar、wstring、u16string、u32string

TODO:  字符串还没有指定任何编码并且传输对它是不可知的，这意味着它通常只能包含 ASCII 但所有端点也可以“同意”使用特定的编码

TODO: 在指定到 C++ 和 Python 的映射后考虑删除字节、字符

4.2 非原始字段类型

        除了原始类型之外，还可以引用其他消息来描述“复杂”字段的类型。复杂字段类型由包和消息名称标识。

4.3 具有静态大小的数组

        静态数组正好有 N 个指定类型的元素。 N 必须大于 0。

4.4 具有动态大小的数组

        动态数组可以有 0 到 N 个指定类型的元素。 N 可能没有上限，并且可能仅受内存或其他系统特定限制的限制。

4.5 上限

        字符串和动态数组的大小可以通过上限来限制。这可以为使用动态大小数据的数据结构预分配内存。

五、默认值

5.1 字段可以选择指定默认值。

如果未指定默认值，则使用通用默认值：

• 对于布尔它是错误的
• 对于数字类型，它是 0 值
• 对于字符串，它是一个空字符串
• 对于静态大小的数组，它是一个由 N 个元素组成的数组，其字段为零初始化
• 对于有界大小数组和动态大小数组，它是一个空数组 []

5.2 数组默认值

数组类型的字段可以选择指定默认值。

• 数组的默认值必须以左方括号 ([) 开头并以右方括号 (]) 结尾
• 数组中的每个值都必须用逗号 (,) 分隔
• 数组中的所有值必须与字段的类型相同
• 数组的第一个值之前不能有逗号
• 忽略数组最后一个元素后的逗号

 

5.3 字符串数组的附加规则：

• 字符串数组必须只包含符合以下规则的字符串：
  • 可以选择用单引号 (') 或双引号 (") 引用的字符串值
  • 双引号 (") 字符串（分别是单引号 (')）应该有任何内部双引号（分别是单引号）转义

5.4  常数

        常量由原始类型、名称和固定值定义。 

六、惯例和约定

6.1 消息和服务的命名

        每个文件都包含一个消息或服务。消息文件使用扩展名 .msg，服务文件使用扩展名 .srv。

        两个文件名都必须使用大写的驼峰式名称，并且只能由字母数字字符组成。

6.2 字段命名

        字段名称必须是带有下划线的小写字母数字字符，用于分隔单词。它们必须以字母字符开头，不能以下划线结尾，并且不能有两个连续的下划线。

6.3 常量的命名

        常量名称必须是带有下划线的大写字母数字字符，用于分隔单词。它们必须以字母字符开头，不能以下划线结尾，并且不能有两个连续的下划线。

七、句法

消息和服务定义是文本文件。

7.1 注释

字符 # 开始一个注释，它在它出现的行的末尾终止。

7.2 消息文件格式

        一行可以包含字段定义或常量定义。虽然必须使用单个空格来分隔标记，但可以选择在标记之间插入额外的空格。

7.3 字段定义（Field definition）

字段定义具有以下结构：

<type> <name> <optional_default_value>

7.4 常量定义

        常量定义具有以下结构：

<type> <name>=<value>

7.4 类型

由其基本类型和可选的数组说明符定义。

基本类型可以是以下之一：

• 上面列表中的原始类型：例如整数32

• 具有上限的字符串：string<=N 将字符串的长度限制为 N 个字符
• 引用另一条消息的复杂类型：
  • 消息的绝对引用：例如some_package/SomeMessage
  • 同一包中消息的相对引用：例如其他留言

数组说明符可以是以下之一：

• 静态数组由后缀 [N] 描述，其中 N 是数组的固定大小
• 无界动态数组由后缀 [] 描述
• 有界动态数组由后缀 [<=N] 描述，其中 N 是数组的最大大小

7.5  值（Values）

        根据类型，以下值有效：

• bool:

  • true, 1
  • false, 0

• byte:

  • an unsigned integer value in the following interval [0, 255]

• char:

  • an integer value in the following interval [-128, 127]

• float32 and float64:

  • a decimal number using a dot (.) as the separator between the integer-part and fractional-part.

• int8, int16, int32 and int64:

  • an integer value in the following interval [- 2 ^ (N - 1), 2 ^ (N - 1) - 1] where N is the number of bits behind int

• uint8, uint16, uint32 and uint64:

  • an unsigned integer value in the following interval [0, 2 ^ N - 1] where N is the number of bits behind uint

• string:

  • a string value which can optionally be quoted with either single quotes (') or double quotes (")

  • a double-quoted (") string (respectively single-quoted (')) should have any inner double quotes (respectively single quotes) escaped:

    • string my_string "I heard \"Hello\"" is valid
    • string my_string "I heard "Hello"" is not valid
    • string my_string "I heard 'Hello'" is valid
    • string my_string 'I heard \'Hello\'' is valid
    • string my_string 'I heard 'Hello'' is not valid
    • string my_string 'I heard "Hello"' is valid

八、服务文件格式

        服务文件包含两个消息定义，它们由仅包含三个破折号的行分隔： 

---