diff --git a/articles/142_idl.md b/articles/142_idl.md index 98a6a5074..d9fe18cdf 100644 --- a/articles/142_idl.md +++ b/articles/142_idl.md @@ -40,7 +40,7 @@ Both line comments (`//`) as well as block comments (`/* ... */`) are being supp #### 7.2.3 Identifiers -An identifier must start with an is an ASCII alphabetic characteran followed by any number of ASCII alphabetic, digit and underscore (`_`) characters. +An identifier must start with an ASCII alphabetic character followed by any number of ASCII alphabetic, digit and underscore (`_`) characters. #### 7.2.6 Literals @@ -129,7 +129,7 @@ the DDS-XTypes specification 1.2 defines it with 16-bit. | ---------------------- | ---------------------------------------------------------- | | sequence\ | sequence of items of the specific type\_spec | | | the sequence is unbounded and no maximum size is specified | -| sequence | sequence of of up to N items of the specified type\_spec | +| sequence | sequence of up to N items of the specified type\_spec | | | the sequence is bounded and contain between 0 and N items | #### 7.4.1.4.4.3.2 Strings @@ -159,6 +159,61 @@ An enumerated type consist of an ordered list of enumerators. A multidimensional, fixed-size array is defined by the type of each item and the explicit sizes for each dimension. For now only a one-dimensional, fixed-size array is supported though. +### Interface Identification + +#### Uniform Resource Identifier (URI) + +Following 7.5.1 from the IDL 4.2 specification, every IDL definition can be uniquely identified with a qualified name of the form +**\::\**. +In addition to the specification, the scope of an IDL definition is prefixed with the package name from which the defintion is derived. +This is to guarantee uniqueness of definitions across packages (under the assumption that package names are unique). +Therefore, each interface defintion can be resolved with a URI of the form: **rosidl:\/\/\**. +Where *\* is one or more names separated by forward slashes ("/"). + +#### Uniform Resource Locator (URL) + +For source code to use an interface (e.g. include or import) there needs to be a way to reference the file containing the defintion. +To reference the location of an IDL defintion we use a URL of the form: **package:////**. +Where ** is the relative path from the root of the package where generated defintions can be found. + +#### Example + +Imagine we have a package `foo_pkg` containing an IDL file `Bar.idl` with the following contents: + +```idl +struct MsgA { + boolean bool_member; +}; + +module bar { + const int8 MY_CONSTANT = 42; + + struct MsgB { + int8 int_member; + }; + + module baz { + struct MsgC { + string string_member; + }; + }; +}; +``` + +Also imagine the message generation pipeline places the generated implementation to a subfolder `interface`. + +Then, we can reference the interfaces with the following URIs: + +- `rosidl:foo_pkg/MsgA` +- `rosidl:foo_pkg/bar/MY_CONSTANT` +- `rosidl:foo_pkg/bar/MsgB` +- `rosidl:foo_pkg/bar/baz/MsgC` + +And all can be located with the URL: `package://foo_pkg/interface/bar`. + +For example, the definitions could be included in C++ with `#include ` +or imported in Python with `import foo_pkg.interface.bar`. + ### Annotations The syntax for arbitrary annotations is supported. diff --git a/articles/143_legacy_interface_definition.md b/articles/143_legacy_interface_definition.md index 70c67d9b7..a66163792 100644 --- a/articles/143_legacy_interface_definition.md +++ b/articles/143_legacy_interface_definition.md @@ -38,22 +38,50 @@ Each field is described by a *type* and a *name*. A single data structure is called *message*. Each message has a *name*. -Together with the name of the *package* a message can be uniquely identified. ### Services For request / reply style communication the two exchanged data structures are related. These pairs of data structures are called *services*. -A service is identified by its *name* and the *package* it is in. Each service describes two messages, one for the request data structure, one for the reply data structure. ### Actions For longer running request / reply style communication with feedback about the progress the exchanged data structures are related. These triplets of data structures are called *actions*. -An action is identified by its *name* and the *package* it is in. Each action describes three messages, one for the goal data structure, one for the result data structure, and one for the feedback data structure. +### Identifying data structures + +Every data structure can be uniquely referenced with a *uniform resource identifier* (URI) and a *uniform resource locator* (URL) +as described by [IDL - Interface Identification](idl_interface_definition.html#interface-identification) + +#### Messages + +- URI: `rosidl:/msg/` +- URL: `package:///msg/` + +#### Services + +- URI: `rosidl:/srv/` +- URL: `package:///srv/` + +The underlying message definitions that make up a service are located in the same file (ie. have the same URL) and are in the `srv` namespace: + +- URI: `rosidl:/srv/_Request` +- URI: `package:///srv/_Response` + +#### Actions + +- URI: `rosidl:/action/` +- URL: `package:///action/` + +The underlying message and service definitions that make up an action are located in the same file (ie. have the same URL) and are in the `action` namespace: + +- URI: `rosidl:/action/_Goal` +- URI: `rosidl:/action/_Result` +- URI: `rosidl:/action/_Feedback` + ### Field types The type of a field can be either a primitive type or another data structure.