3.4 Creating User Data Types with Extensible Markup Language (XML)

You can describe user data types with Extensible Markup Language (XML) notation. Connext DDS provides DTD and XSD files that describe the XML format; see <NDDSHOME>/resource/app/app_support/rtiddsgen/schema/rti_dds_topic_types.dtd and <NDDSHOME>/resource/app/app_support/rtiddsgen/schema/rti_dds_topic_types.xsd, respectively. (<NDDSHOME> is described in Paths Mentioned in Documentation.)

The XML validation performed by RTI Code Generator always uses the DTD definition. If the <!DOCTYPE> tag is not in the XML file, RTI Code Generator will look for the default DTD document in <NDDSHOME>/resource/schema. Otherwise, it will use the location specified in <!DOCTYPE>.

We recommend including a reference to the XSD/DTD files in the XML documents. This provides helpful features in code editors such as Visual Studio® and Eclipse™, including validation and auto-completion while you are editing the XML. We recommend including the reference to the XSD document in the XML files because it provides stricter validation and better auto-completion than the DTD document.

To include a reference to the XSD document in your XML file, use the attribute
xsi:noNamespaceSchemaLocation in the <types> tag. For example :

<?xml version="1.0" encoding="UTF-8"?>
<types xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:noNamespaceSchemaLocation=
"<NDDSHOME>/resource/app/app_support/rtiddsgen/schema/rti_dds_topic_types.xsd">
    ...
</types>

To include a reference to the DTD document in your XML file, use the <!DOCTYPE> tag. For example:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE types SYSTEM "<NDDSHOME>/resource/app/app_support/rtiddsgen/schema/rti_dds_topic_types.dtd"> <types> ... </types>

Table 3.12 Mapping Type System Constructs to XML shows how to map the type system constructs into XML. For information on the annotations in the table, see 3.3.9 Using Builtin Annotations.

Table 3.12 Mapping Type System Constructs to XML

Type/Construct

Example

IDL

XML

IDL

XML

char

char8

char char_member;
<member name="char_member"
type="char8"/>

wchar

char32

wchar wchar_member; 
<member name="wchar_member"
type="char32"/>

octet

byte

octet octet_member; 
<member name="octet_member"
type="byte"/>

short

int16

short short_member; 
<member name="short_member"
type="int16"/>

unsigned short

uint16

unsigned short
unsigned_short_member;
<member name="unsigned_short_member"
type="uint16"/>

long

int32

long long_member; 
<member name="long_member"type="int32"/> 

unsigned long

uint32

unsigned long
unsigned_long_member;
<member name= "unsigned_long_member"
type="uint32"/>

long long

int64

long long 
long_long_member;
<member name="long_long_member"
type="int64"/>

unsigned long long

uint64

unsigned long long 
unsigned_long_long_member;
<member name="unsigned_long_long_member"
type="uint64"/>

float

float32

float float_member; 
<member name="float_member"
type="float32"/>

double

float64

double double_member;
<member name="double_member"
type="float64"/>

long double

float128

long double
long_double_member;
<member name= "long_double_member"
type="float128"/>

boolean

boolean

struct PrimitiveStruct {
boolean boolean_member;
};
<struct name="PrimitiveStruct">
<member name="boolean_member"
type="boolean"/>
</struct>

unbounded string

string without stringMaxLength attribute or with stringMaxLength set to -1

struct PrimitiveStruct {
string string_member;
};
<struct name="PrimitiveStruct">
<member name="string_member"
type="string"/>
</struct>

or

 
<struct name="PrimitiveStruct">
<member name="string_member"
type="string"
stringMaxLength="-1"/>
</struct>

bounded string

string with stringMaxLength attribute

struct PrimitiveStruct {
string<20> string_member;
};
<struct name="PrimitiveStruct">
<member name="string_member"
type="string"
stringMaxLength="20"/>
</struct>

unbounded wstring

wstring without stringMaxLength attribute or with stringMaxLength set to -1

struct PrimitiveStruct {
wstring wstring_member;
};
<struct name="PrimitiveStruct">
<member name="wstring_member"
type="wstring"/>
</struct>

or

 
<struct name="PrimitiveStruct">
<member name="wstring_member"
type="wstring"
stringMaxLength="-1"/>
</struct>

bounded wstring

wstring with stringMaxLength attribute

struct PrimitiveStruct { 
wstring<20> wstring_member;
};
<struct name="PrimitiveStruct">
<member name="wstring_member"
type="wstring" stringMaxLength="20"/>
</struct>

enum

enum tag

enum PrimitiveEnum {
ENUM1,
ENUM2,
ENUM3
};
<enum name="PrimitiveEnum">  
<enumerator name="ENUM1"/>
<enumerator name="ENUM2"/>
<enumerator name="ENUM3"/>
</enum>
enum PrimitiveEnum {
  ENUM1=10,
  ENUM2=20,
  ENUM3
}
enum PrimitiveEnum {
  @value (10) ENUM1,
  @value (20) ENUM2,
  @value (30) ENUM3
}
<enum name="PrimitiveEnum">
<enumerator name="ENUM1" value="10"/>
<enumerator name="ENUM2" value="20"/>
<enumerator name="ENUM3" value="30"/>
</enum>

constant

const tag

const double PI = 3.1415;
<const name="PI" type="double"
value="3.1415"/>

struct

struct tag

struct PrimitiveStruct {
short short_member;
};
<struct name="PrimitiveStruct">
<member name="short_member"
type="short"/>
</struct>

union

union tag

union PrimitiveUnion switch
(long) {
case 1:
short short_member;
case 2:
case 3:
float float_member;
default:
long long_member;
};
<union name="PrimitiveUnion">
<discriminator type="long"/>
<case>
<caseDiscriminator value="1"/>
<member name="short_member"
type="short"/>
</case>

<case>
<caseDiscriminator value="2"/>
<caseDiscriminator value="3"/>
<member name="float_member"
type="float"/>
</case>

<case>
<caseDiscriminator value="default"/>
<member name="long_member"
type="long"/>
</case>
</union>

valuetype

valuetype tag

valuetype BaseValueType {
public long long_member;
};

valuetype DerivedValueType:
BaseValueType {
public long
long_member_2;
};
<valuetype name="BaseValueType">
<member name="long_member"
type="long" visibility="public"/>
</valuetype>

<valuetype name="DerivedValueType"
baseClass="BaseValueType">
<member name="long_member_2"
type="long" visibility="public"/>
</valuetype>

typedef

typedef tag

typedef short ShortType;
<typedef name="ShortType" type="short"/>
struct PrimitiveStruct {
short short_member;
};
typedef PrimitiveStruct
PrimitiveStructType;
<struct name="PrimitiveStruct">
<member name="short_member"
type="short"/>
</struct>

<typedef name="PrimitiveStructType"
type="nonBasic" nonBasicTypeName="PrimitiveStruct"/>

arrays

Attribute
arrayDimensions

struct OneArrayStruct {
short short_array[2];
};
<struct name="OneArrayStruct">
<member name="short_array"
type="short" arrayDimensions="2"/>
</struct>
struct TwoArrayStruct {
short short_array[1][2];
};
<struct name="TwoArrayStruct">
<member name="short_array"
type="short" arrayDimensions="1,2"/>
</struct>

bounded sequence

Attribute sequenceMaxLength > 0

struct SequenceStruct {
sequence<short,4>
short_sequence;
};
<struct name="SequenceStruct">
<member name="short_sequence"
type="short"
sequenceMaxLength="4"/>
</struct>

unbounded sequence

Attribute sequenceMaxLength set to -1

struct SequenceStruct {
sequence<short>
short_sequence;
};
<struct name="SequenceStruct">
<member name="short_sequence"
type="short"
sequenceMaxLength="-1"/>
</struct>

array of sequences

Attributes sequenceMaxLength and arrayDimensions

struct 
ArrayOfSequencesStruct {
sequence<short,4>
short_sequence_array[2];
};
<struct name= "ArrayOfSequenceStruct">
<member name=
"short_sequence_array"
type="short" arrayDimensions="2"
sequenceMaxLength="4"/>
</struct>

sequence of arrays

Must be implemented with a typedef tag

typedef short
ShortArray[2];
 
struct 
SequenceOfArraysStruct {
sequence<ShortArray,2>
short_array_sequence;
};
<typedef name="ShortArray"
type="short" dimensions="2"/>
<struct name=
"SequenceOfArrayStruct">
<member name= "short_array_sequence"
type="nonBasic"
nonBasicTypeName="ShortSequence"
sequenceMaxLength="2"/>
</struct>

sequence of sequences

Must be implemented with a typedef tag

typedef sequence<short,4>
ShortSequence;
 
struct 
SequenceOfSequencesStruct {
sequence<ShortSequence,2>
short_sequence_sequence;
};
<typedef name="ShortSequence"
   type="short"sequenceMaxLength="4"/>
<struct name="SequenceofSequencesStruct">
<member name="short_sequence_sequence"
type="nonBasic"
nonBasicTypeName="ShortSequence"
sequenceMax-Length="2"/>
</struct>

module

module tag

module PackageName {
struct PrimitiveStruct {
long long_member;
};
};
<module name="PackageName">
<struct name="PrimitiveStruct">
<member name="long_member"
type="long"/>
</struct>
</module>

include

include tag

#include 
"PrimitiveTypes.idl"
<include file="PrimitiveTypes.xml"/>

@key annotation 1For information on this and the other annotations, see Using Builtin Annotations (Section 1.0.1  on page 1).

key attribute with values
true, false, 0, or 1

Default (if not present): 0

struct KeyedPrimitiveStruct {
  @key short 
    short_member;
};
<struct name="KeyedPrimitiveStruct">
<member name="short_member"
type="short" key="true"/>
</struct>

@external or pointer

external attribute with values true, false, 0, or 1

Default (if not present): 0

struct PrimitiveStruct 
{
  @external long 
    long_member;
};
<struct name="PointerStruct">
    <member name="long_member"
      type="long"
      external="true"/>
</struct>

@optional annotation

optional attribute with values true, false, 0 ,or 1

Default (if not present): 0

struct Point {
  long x;
  long y;
  @optional long z;
};
<struct name= "Point">
  <member name="x" type="int32"/>
  <member name="y" type="int32"/>
  <member name="z" type="int32" optional="true"/>
</struct>

@id annotation

id attribute

Default (if not present): id calculated based on the @autoid value of the enclosing type and module(s)

@mutable
struct Point {
  @id(56) long x;
  @id(57) long y;
  long z;
};
<struct name="Point" extensibility="mutable">
  <member name="x" id="56" type="long"/>
  <member name="y" id="57" type="long"/>
  <!-- z id is 58 -->
  <member name="y" type="long"/>
</struct>

@hashid annotation

hashid attribute containing the string that must be hashed to compute the id

Default (if not present). id calculated based on the @autoid value of the enclosing type and module(s)

@mutable
struct Point {
  @hashid long x;
  @hashid(“other_y”) 
  long y;
};
<struct name= "Point" extensibility= "mutable">
  <member name="x" hashid="x" type="int32"/>
  <member name="y" hashid="other_y" type="int32"/>
</struct>

@value annotation

value attribute

Default (if not present): value of the previous enumerator plus 1

enum PrimitiveEnum {
  @value (10) ENUM1,
  @value (20) ENUM2,
ENUM3
} 
<enum name="PrimitiveEnum">
  <enumerator name="ENUM1" value="10"/>
  <enumerator name="ENUM2" value="20"/>
  <!-- ENUM3 id is 21 --> 
  <enumerator name="ENUM3"/>
</enum>

@default_literal annotation

defaultLiteral attribute with values true, false, 0, or 1

Default (if not present): 0

enum MyEnum {
    ENUM1,
    @default_literal ENUM2
};
<enum name="MyEnum">
    <enumerator name="ENUM1"/>
    <enumerator name="ENUM2" defaultLiteral="true"/>
</enum>

@default annotation

default attribute

Default (if not present in this member or its alias types): 0, the empty string, or whichever enumerator is the defaultLiteral

@default(24)
typedef long MyLongTypedefWithDefault;

struct Point { 
    @default(42) 
    long x; 
    MyLongTypedefWithDefault y; 
}; 
<typedef name="MyLongTypedefWithDefault" type="long" default="24"/> 
<struct name="Point"> 
    <member name="x" type="long" default="42"/> 
    <member name="y" type="nonBasic" nonBasicTypeName="MyLongTypedefWithDefault"/> <!-- default is 24 -->
</struct> 

@min annotation

min attribute

Default (if not present in this member or its alias types): the minimum possible value of the type

struct Point { 
    @min(-32) 
    long x; 
    long y; 
}; 
<struct name="Point"> 
    <member name="x" type="long" min="-32"/> 
    <member name="y" type="long"/> 
</struct> 

@max annotation

max attribute

Default (if not present in this member or its alias types): the maximum possible value of the type

struct Point {
    @max(31)
    long x;
    long y;
};
<struct name="Point">
    <member name="x" type="long" max="31"/>
    <member name="y" type="long"/>
</struct>

@range annotation

Not supported. Use min and max attributes instead.

struct Point {
    @range(min = -32, max = 31)
    long x;
    long y;
};
<struct name="Point">
    <member name="x" type="long" min="32" max="31"/>
    <member name="y" type="long"/>
</struct>

@autoid annotation

autoid attribute with "hash" or "sequential" values

Default (if not present): the @autoid value in ancestor module(s) or sequential if not specified

@mutable
@hashid(HASH)
struct Point {
  long x;
  long y;
};
<struct name="Point" extensibility="mutable" autoid="hash">
  <member name="x" type="long"/>
  <member name="y" type="long"/>
</struct>

@nested or @top-level annotation

nested attribute with values true, false, 0 ,or 1

Default (if not present): 0

@nested
struct
TopLevelPrimitiveStruct {
short short_member;
};

or

 
@top_level(false)
struct TopLevelPrimitiveStruct {
short short_member;
};
<struct name=
  "TopLevelPrimitiveStruct"
   nested="true">
<member name=
   "short_member"
    type="short"/>
</struct>

@extensibility, @mutable, @appendable, or @final annotation

extensibility attribute with values final, appendable, or mutable

Default (if not present): appendable

@mutable
struct Point {
    long x;
    long y;
};
<struct name="Point" extensibility="mutable">
    <member name="x" type="long"/>
    <member name="y" type="long"/>
</struct>

@allowed_data_representation

allowed_data_representation attribute with values xcdr, xcdr2, or xml

Default (if not present): xcdr2 for FlatData language binding; the @allowed_data_representation value in ancestor module(s) or (xcdr|xcdr2) for plain language binding

@allowed_data_representation(XCDR2)
@mutable
struct Point {
  long x;
  long y;
};
<struct name= "Point" extensibility= "mutable" allowed_data_representation="xcdr2">
  <member name="x" type="int32"/>
  <member name="y" type="int32"/>
</struct>

@use_vector

useVector attribute with values true, false, 0 ,or 1

Default (if not present): false unless code generated with -alwaysUseStdVector

struct Image {
  @use_vector
  sequence<octet, 1048576> pixels;
};
<struct name= "Image">
  <member name="pixels"  sequenceMaxLength="1048576" useVector="true" type="byte"/>
</struct>

@language_binding annotation

languageBinding attribute with values plain or flat_data.

Default (if not present): the @language_binding value in ancestor module(s) or plain if not specified

@language_binding(FLAT_DATA)
@final
struct Point {
    long x;
    long y;
};
<struct name="Point" extensibility=”final” languageBinding="flat_data">
    <member name="x" type="long"/>
    <member name="y" type="long"/>
</struct>

@transfer_mode annotation

transferMode attribute with values inband or shmem_ref.

Default (if not present): the @transfer_mode value in ancestor module(s) or inband if not specified

@transfer_mode(SHMEM_REF)
struct Point {
    long x;
    long y;
};
<struct name="Point" transferMode="shmem_ref">
    <member name="x" type="long"/>
    <member name="y" type="long"/>
</struct>

@resolve-name annotation

resolveName attribute with values true, false, 0, or 1

Default (if not present): @resolve_name of the parent type or false if not specified on parent

struct 
UnresolvedPrimitiveStruct {
  @resolve_name(false)
  PrimitiveStruct
primitive_member;
};
<struct name=
"UnresolvedPrimitiveStruct">
<member name="primitive_member"
type="PrimitiveStruct"
resolveName="false"/>
</struct>

Other annotations

directive tag

//@copy (This text will be
copied in the generated files)
<directive kind="copy"> 
This text will be copied in the
generated files
</directive>

© 2020 RTI