RTI Connext
Core Libraries and Utilities
(Experimental Feature)
Getting Started Guide
Version 5.0
RTI Connext
Core Libraries and Utilities
(Experimental Feature)
Getting Started Guide
Version 5.0
© 2012
All rights reserved.
Printed in U.S.A. First printing.
August 2012.
Trademarks
Copy and Use Restrictions
No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form (including electronic, mechanical, photocopy, and facsimile) without the prior written permission of Real- Time Innovations, Inc. The software described in this document is furnished under and subject to the RTI software license agreement. The software may be used or copied only under the terms of the license agreement.
Technical Support
Website: https://support.rti.com/
ii
Contents
iii
Chapter 1 |
Introduction |
DomainParticipants, and all the Entities they contain (Publishers, Subscribers, DataWriters and
DataReaders).
With the traditional approach an application developer must program explicitly into the code the actions needed to join a domain, register the data types it will use, create the
Topics and all the Entities (Publishers, Subscribers, DataRead- ers and DataWriters) that the application uses. Even for sim- ple applications this “system creation” code can result in hundreds of lines of
This document assumes you have a basic understanding of Connext application development and concepts such as Domains, DomainParticipants, Topics, DataWriters and DataReaders. For an overview of these concepts, please read Introduction to Connext, Section 3.2 in the RTI Core Libraries and Utilities Getting Started Guide, which is part of your distribution, or you can find it online at http:// community.rti.com/content/page/ documentation.
underlying APIs. In this manner, an application can be initially developed using
Using
❏The data types that will be used to communicate information in the system
❏The Topics that will be used in the domain, associating each Topic with a data type
❏The DomainParticipants that can potentially be used, giving each a participant name
❏The DataWriters and DataReaders present within each DomainParticipant, each associated with its corresponding Topic.
The application code simply indicates the participant configuration name of the DomainPartici- pant that the application wants to create. The
When the application needs to read or write data, register listeners, or perform any other action, it simply looks up the appropriate Entity by name and uses it.
❏Developers can describe all the Entities that a Connext application will need in an XML file and then create that application with a single function call, saving many hundreds of lines of setup code.
❏Application descriptions written in XML are usable from all programming languages.
❏The complete domain (including the data types and Topics that can be in the domain) may be defined in an XML file and shared amongst all the developers and applications.
❏The Quality of Service (QoS) that should be used for each DomainParticipant, Topic, DataReader, and DataWriter can be fully specified in the XML and shared amongst a group of developers and applications.
❏The XML description of the application can be used in combination with RTI Prototyper to design and prototype application deployment scenarios, allowing quick testing and vali- dation without the need for programming.
To use the companion RTI Connext Prototyper, see Chapter 3.
Chapter 2 A ‘Hello, World’ Example
This chapter assumes that you have installed the RTI Connext Core Libraries and Utilities and con- figured your environment correctly. If you have not done so, please follow the steps in the RTI Core Libraries and Utilities Getting Started Guide, specifically Chapter 2 “Installing RTI Connext” and Section 3.1 “Building and running Hello World” in Chapter 3. The guide is part of your dis- tribution; you can also find it online at http://community.rti.com/content/page/documenta- tion. The guide will assist you in the correct setting of both your environment variable NDDSHOME and, depending on your architecture, the environment variable PATH (on Win- dows Systems), LD_LIBRARY_PATH (on Linux systems), or DYLD_LIBRARY_PATH (on MacOS Systems).
2.1Hello World using XML and Dynamic Data
The files for this example are located in the directory <installation directory>/example/CPP/ HelloWorld_xml_dynamic. This simple scenario consists of two applications, illustrated in the figure below: HelloWorld_publisher.exe which writes the Topic, HelloWorldTopic, and HelloWorld_subscriber.exe which subscribes to that Topic.
Figure 2.1 Hello World Domain
First we will run the application, then we will examine the configuration file and source code.
Hello World using XML and Dynamic Data
2.1.1Build the Application
The example code is provided in C++, C#, and Java. The following instructions describe how to build it on Windows and
(RTI_CoreLibrariesAndUtilities_GettingStarted_EmbeddedSystemsAddendum.pdf) for instructions specific to these platforms.
To build the example C++ applications on a Windows System:
1.In Windows Explorer, go to <installation directory>\exam- ple\CPP\HelloWorld_xml_dynamic\win and open the Microsoft® Visual Studio® solution file for your architecture. For example, the file for Visual Studio 2008
2.The Solution Configuration combo box in the toolbar indicates whether you are building debug or release executables; select Release. Then select Build Solution from the Build menu.
To build the example C++ applications on a
1.From your command shell, change directory to <installation directory>/example/CPP/ HelloWorld_xml_dynamic.
2.Type:
> gmake
where <architecture> is one of the supported architectures (e.g., Make- file.i86Linux2.6gcc4.4.5); see the contents of the make directory for a list of available architectures. This command will build a release executable. To build a debug version instead, type:
>gmake
2.1.2Run the Application
The previous step should have built two executables: HelloWorld_subscriber and HelloWorld_publisher. These applications should be in proper architecture subdirectory under the objs directory. For example, objs\i86Win32VS2008 in the Windows example cited below and objs/i86Linux2.6gcc4.4.5 in the Linux example.
To start the subscribing application on a Windows system:
From your command shell, go to <installation directory>\exam- ple\CPP\HelloWorld_xml_dynamic and type:
> objs\<architecture>\HelloWorld_subscriber.exe
where <architecture> is the architecture you just built; look in the objs directory to see the name of the architecture you built. For example, the Windows architecture name corre- sponding to
To start the subscribing application on a
From your command shell, change directory to <installation directory>/example/CPP/ HelloWorld_xml_dynamic and type:
> objs/<architecture>/HelloWorld_subscriber
where <architecture> is the architecture you just built; look in the objs directory to see the name of the architecture you built. For example, i86Linux2.6gcc4.4.5.
You should immediately see some messages from the publishing application showing that it is writing data and messages from the subscribing application showing the data it receives. Do not
Hello World using XML and Dynamic Data
worry about the contents of the messages. They are generated automatically for this example. The important thing is to understand how the application is defined, which will be explained in the following sections.
2.1.3Examine the XML Configuration Files Definition
A Connext application is defined in the file USER_QOS_PROFILES.xml found in the directory
<installation directory>/example/CPP/HelloWorld_xml_dynamic. Let’s review its content to see how this scenario was constructed. The main sections in the file are:
❏QoS definition section
❏Type definition section
❏Domain definition section
❏Participant definition section
The entire file is shown below. The we will examine the file
<dds
version="5.0.0">
<qos_library name="qosLibrary"> <qos_profile name="DefaultProfile"> </qos_profile>
</qos_library>
<const name="MAX_NAME_LEN" type="long" value="64"/> <const name="MAX_MSG_LEN" type="long" value="128"/>
<struct name="HelloWorld">
<member name="sender" type="string" key="true" stringMaxLength="MAX_NAME_LEN"/>
<member name="message" type="string" stringMaxLength="MAX_MSG_LEN"/>
<member name="count" type="long"/> </struct>
</types>
<domain_library name="MyDomainLibrary" >
<domain name="HelloWorldDomain" domain_id="0"> <register_type name="HelloWorldType"
kind="dynamicData" type_ref="HelloWorld" />
<topic name="HelloWorldTopic" register_type_ref="HelloWorldType">
<topic_qos name="HelloWorld_qos" base_name="qosLibrary::DefaultProfile"/>
</topic>
</domain>
</domain_library>
Hello World using XML and Dynamic Data
<participant_library name="MyParticipantLibrary">
<domain_participant name="PublicationParticipant" domain_ref="MyDomainLibrary::HelloWorldDomain"> <publisher name="MyPublisher">
<data_writer name="HelloWorldWriter" topic_ref="HelloWorldTopic"/>
</publisher> </domain_participant>
<domain_participant name="SubscriptionParticipant" domain_ref="MyDomainLibrary::HelloWorldDomain"> <subscriber name="MySubscriber">
<data_reader name="HelloWorldReader" topic_ref="HelloWorldTopic"> <datareader_qos name="HelloWorld_reader_qos"
base_name="qosLibrary::DefaultProfile"/> </data_reader>
</subscriber> </domain_participant>
</participant_library>
2.1.3.1QoS Definition
The DDS Entities that are defined have an associated QoS. The QoS section of the XML file pro- vides the means to define QoS libraries and profiles that can be used to configure the QoS of the defined Entities.
The syntax of the QoS libraries and profiles section is described in the RTI Core Libraries and Util- ities User’s Manual, Chapter 15 “Configuring QoS with XML.”
In this example, the QoS library and profile are empty, just to provide a placeholder where the QoS can be specified. Using this empty profile results in the default DDS QoS being used:
<qos_library name="qosLibrary"> <qos_profile name="DefaultProfile"> </qos_profile>
</qos_library>
2.1.3.2Type Definition
The data associated with the HelloWorld Topic consists of two strings and a numeric counter:
❏The first string contains the name of the sender of the message. This field is marked as “key” as signals the identity of the
❏The second string contains a message.
❏The third field is a simple counter which the application increments with each message.
This example uses the dynamic data API, so the data type must be defined in the XML configu- ration. This is accomplished by adding the type definition within the <types> tag:
Hello World using XML and Dynamic Data
<types>
<const name="MAX_NAME_LEN" type="long" value="64"/> <const name="MAX_MSG_LEN" type="long" value="128"/>
<struct name="HelloWorld">
<member name="sender" type="string" key="true" stringMaxLength="MAX_NAME_LEN"/>
<member name="message" type="string" stringMaxLength="MAX_MSG_LEN"/> <member name="count" type="long"/>
</struct>
</types>
The <types> tag may be used to define a library containing the types that the different applica- tions will need. However, for this simple example just one
2.1.3.3Domain Definition
The domain section is used to define the system’s Topics and the corresponding data types asso- ciated with each Topic. To define a Topic, the associated data type must be registered with the domain giving it a registered type name. The registered type name is used to refer to that data type within the domain at the time the Topic is defined.
In this example, the configuration file registers the previously defined HelloWorld type under the name HelloWorldType and then defines a topic with name HelloWorldTopic associated with the registered type, referring to it by its registered name HelloWorldType:
<domain_library name="MyDomainLibrary" domain_id=”0” > <domain name="HelloWorldDomain">
<register_type name="HelloWorldType"
kind="dynamicData" type_ref="HelloWorld"/>
<topic name="HelloWorldTopic" register_type_ref="HelloWorldType"/>
</domain> </domain_library>
Note that attribute type_ref in the <register_type> element refers to the same HelloWorld type defined in the <types> section.
A domain definition may register as many data types and define as many Topics as it needs. In this example a single data type and Topic suffices.
Note that domain_library can be used to define multiple domains. However in this example only one domain is used.
2.1.3.4Participant Definition
The participant section is used to define the DomainParticipants in the system and the DataWrit- ers and DataReaders that each participant has. DomainParticipants are defined within the <participant_library> tag.
Each DomainParticipant:
❏Has a unique name (within the library) which will be used later by the application that creates it.
❏Is associated with a domain, which defines the domain_id, Topics and data types the
DomainParticipant will use.
Hello World using XML and Dynamic Data
❏Defines the Publishers and Subscribers within the DomainParticipant. Publishers contain DataWriters and Subscribers contain DataReaders.
❏Defines the set of DataReaders it will use to write data. Each DataReader has a QoS and a unique name which can be used from application code to retrieve it.
❏Defines the set of DataWriters it will use to write data. Each DataWriter has a QoS and a unique name which can be used from application code to retrieve it.
❏Optionally the Participants, Publishers, Subscribers, DataWriters and DataReaders can spec- ify a QoS profile that will be used to configure them.
The example below defines two DomainParticipant entities called PublicationParticipant and
SubscriptionParticipant:
<participant_library name="MyParticipantLibrary">
<domain_participant name="PublicationParticipant" domain_ref="MyDomainLibrary::HelloWorldDomain">
<publisher name="MyPublisher"> <data_writer name="HelloWorldWriter"
topic_ref="HelloWorldTopic"/> </publisher>
</domain_participant>
<domain_participant name="SubscriptionParticipant" domain_ref="MyDomainLibrary::HelloWorldDomain">
<subscriber name="MySubscriber">
<data_reader name="HelloWorldReader" topic_ref="HelloWorldTopic">
<datareader_qos name="HelloWorld_reader_qos" base_name="qosLibrary::DefaultProfile"/>
</data_reader>
</subscriber> </domain_participant
</participant_library>
Examining the XML we see that:
❏The PublicationParticipant bound to the domain MyDomainLibrary::HelloWorldDo- main.
❏The participant contains a single Publisher (with name MyPublisher which itself con- tains a single DataWriter named HelloWorldWriter.
❏The DataWriter writes the Topic HelloWorldTopic which is defined in the domain MyDo- mainLibrary::HelloWorldDomain.
Similarly:
❏The SubscriptionParticipant is also bound to the domain MyDomainLibrary::Hello- WorldDomain.
❏The participant contains a single Subscriber (with name MySubscriber which itself con- tains a single DataReader named HelloWorldReader.
❏The DataReader reads the topic HelloWorldTopic which is defined in the domain MyDo- mainLibrary::HelloWorldDomain.
Hello World using XML and Dynamic Data
Since both participants are in the same domain and the HelloWorldWriter DataWriter writes the same Topic that the HelloWorldReader DataReader reads the two participants will communicate as was illustrated in Figure 2.1, “Hello World Domain,” on page
2.1.4Publisher Application
Open the file <installation directory>/examples/CPP/HelloWorld_publisher.cxx and look at the source code.
The logic of this simple application is contained in the publisher_main() function. The logic can be seen as composed of two parts:
❏Entity Creation
❏Use of the Entities
Entity Creation: The application first creates a DomainParticipant using the function create_participant_from_config_exp() this function takes the configuration name of the partici- pant MyParticipantLibrary::PublicationParticipant which is the same name that was specified in the XML file. Note that the name in the XML file PublicationParticipant has been qualified with the name of the library it belongs to MyParticipantLibrary.
DDSDomainParticipant * participant =
"MyParticipantLibrary::PublicationParticipant", participant_name);
This single function call registers all the necessary data types and creates and the Topics and Entities that were specified in the XML file. In this simple case the participant only contains a Publisher MyPublisher with a single DataWriter HelloDataWriter. However, in more realistic scenarios this single call can create hundreds of entities (both readers and writers).
Use of the Entities: The remaining part of the function uses the created Entities to perform the logic of the program.
This example writes data using the single DataWriter. So the application looks up the Hello- WorldWriter DataWriter using the fully qualified name MyPublisher::HelloWorldWriter and nar- rows it to be a DynamicDataWriter:
DDSDynamicDataWriter * dynamicWriter = DDSDynamicDataWriter::narrow(
"MyPublisher::HelloWorldWriter"));
Once the DataWriter is available, some data objects need to be created and used to send the data. As this example uses dynamic data, and the type code is internally created, you can use the operations create_data() and delete_data() in a DataWriter to create and delete a data object. This is achieved with the calls seen below:
/* Create data */
DDS_DynamicData *dynamicData = dynamicWriter->create_data_exp( DDS_DYNAMIC_DATA_PROPERTY_DEFAULT);
/* Main loop to repeatedly send data */ for (count=0; count < 100 ; ++count) {
/* Set the data fields */
retcode = dynamicData->set_string( "sender",
DDS_DYNAMIC_DATA_MEMBER_ID_UNSPECIFIED,
"John Smith");
Hello World using XML and Dynamic Data
retcode = dynamicData->set_string( "message",
DDS_DYNAMIC_DATA_MEMBER_ID_UNSPECIFIED, "Hello World!");
retcode = dynamicData->set_long( "count",
DDS_DYNAMIC_DATA_MEMBER_ID_UNSPECIFIED, count);
/* Write the data */
retcode =
...
}
/* Delete data sample */
Note that the operations, such as set_long() are used to set the different attributes of the dynam- icData object. These operations refer to the attribute names (e.g., “count”) that were defined as part of the data type.
2.1.5Subscriber Application
Open the file <installation directory>/examples/CPP/HelloWorld_subscriber.cxx and look at the source code.
The logic of this simple application is contained in the subscriber_main() function. Similar to the publisher application the logic can be seen as composed of two parts:
❏Entity Creation
❏Use of the Entities
Entity Creation: The application first creates a DomainParticipant using the function create_participant_from_config_exp(). This function takes the configuration name of the partic- ipant MyParticipantLibrary::SubscriptionParticipant which is the same name that was speci- fied in the XML file. Notice that the name in the XML file SubscriptionParticipant has been qualified with the name of the library it belongs to MyParticipantLibrary.
DDSDomainParticipant * participant =
"MyParticipantLibrary::SubscriptionParticipant”, participant_name);
This single function call registers all the necessary data types and creates and the Topics and Entities that were specified in the XML file. In this simple case the participant only contains a subscriber MySubscriber with a single DataReader HelloDataReader. However in more realistic scenarios this single call can create hundreds of Entities (both DataReaders and DataWriters).
Use of the Entities: The remaining part of the function uses the entities that were created to per- form the logic of the program.
This example only needs to read data using the single DataReader. So the application looks up the HelloWorldReader DataReader using the fully qualified name MySubscriber::HelloWorldReader and narrows it to be a DynamicDataReader:
DDSDynamicDataReader * dynamicReader = DDSDynamicDataReader::narrow(
To process the data, the application installs a Listener on the DataReader. The HelloWorldLis- tener, defined on the same file implements the DataReaderListener interface, which the DataReader uses to notify the application of relevant events, such as the reception of data.
Hello World using XML and Dynamic Data
/* Create a DataReaderListener */
HelloWorldListener * reader_listener = new HelloWorldListener();
/* set listener */
retcode =
The last part is the implementation of the listener functions. In this case, we only implement the on_data_available() operation which is the one called when data is received.
The on_data_available() function receives all the data into a sequence and then uses the DDS_DynamicData::print() function to print each data item received.
void HelloWorldListener::on_data_available(DDSDataReader* reader)
{
DDSDynamicDataReader * ddDataReader = NULL; DDS_DynamicDataSeq dataSeq; DDS_SampleInfoSeq infoSeq;
DDS_ReturnCode_t retcode = DDS_RETCODE_ERROR; DDS_Long i = 0;
ddDataReader = DDSDynamicDataReader::narrow(reader);
retcode =
dataSeq, infoSeq, DDS_LENGTH_UNLIMITED,
DDS_ANY_SAMPLE_STATE, DDS_ANY_VIEW_STATE, DDS_ANY_INSTANCE_STATE);
printf("on_data_available:%s\n",
for (i = 0; i < dataSeq.length(); ++i) { if (infoSeq[i].valid_data) {
retcode = dataSeq[i].print(stdout, 0);
}
}
retcode =
}
2.1.6Subscribing with a Content Filter
To use a content filter, modify the SubscriptionParticipant configuration to look like this:
<participant_library name="MyParticipantLibrary">
...
<domain_participant name="SubscriptionParticipant" domain_ref="MyDomainLibrary::HelloWorldDomain">
<subscriber name="MySubscriber">
<data_reader name="HelloWorldReader" topic_ref="HelloWorldTopic">
<datareader_qos name="HelloWorld_reader_qos" base_name="qosLibrary::DefaultProfile"/>
<filter name="HelloWorldTopic" kind="builtin.sql">
<expression> count > 2 |
</expression> |
</filter> |
|
</data_reader> |
|
</subscriber> |
|
</domain_participant> |
|
</participant_library> |
|
Hello World using XML and Compiled Types
The extra XML within the <filter> tag adds a SQL content filter which only accepts samples with the field count greater than two.
Now run HelloWorld_subscriber without recompiling and check the expected that the behav- ior.
2.2Hello World using XML and Compiled Types
The files for this example are located in the directory <installation directory>/example/CPP/ HelloWorld_xml_compiled. This simple scenario consists of two applications identical in pur- pose to the one illustrated in Figure 2.1, “Hello World Domain,” on page
In contrast with previous example, which uses the DynamicData API, this example uses com- piled types.
Compiled types are syntactically nicer to use from application code and provide better perfor- mance. The drawback is that there is an extra step of
2.2.1Define the Data Types using IDL or XML
The first step is to describe the
The directory <installation directory>/example/CPP/HelloWorld_xml_compiled contains the XML description of the data type in the file HelloWorld.xml and it also contains the equivalent IDL description in HelloWorld.idl.
Let’s examine the contents of the XML file:
<?xml version="1.0"
<types
rti_dds_topic_types.xsd">
<const name="MAX_NAME_LEN" type="long" value="64"/> <const name="MAX_MSG_LEN" type="long" value="128"/>
<struct name="HelloWorld">
<member name="sender" type="string" key="true" stringMaxLength="MAX_NAME_LEN"/>
<member name="message" type="string" stringMaxLength="MAX_MSG_LEN"/> <member name="count" type="long"/>
</struct>
</types>
The file defines a structure type called “HelloWorld” consisting of a string (the sender), a string (the message), and an integer count. Note that the
Hello World using XML and Compiled Types
2.2.2Generate
This step produces code to support the direct use of the structure ‘HelloWorld’ from application code. The code is generated using the provided tool named rtiddsgen.
The
To generate code, follow these steps (replacing <architecture> as needed for your system; e.g., i86Win32VS2008 or i86Linux2.6gcc4.4.5):
On a Windows system:
From your command shell, change directory to <installation directory>/exam- ple\CPP\HelloWorld_xml_compiled and type:
rtiddsgen
On a
From your command shell, change directory to <installation directory>/example/CPP/ HelloWorld_xml_dynamic and type:
rtiddsgen
As a result of this step you will see the following files appear in the directory
HelloWorld_xml_dynamic: HelloWorld.h, HelloWorld.cxx, HelloWorldPlugin.h, HelloWorld- Plugin.cxx, HelloWorldSupport.h, and HelloWorldSupport.cxx
The most notable thing at this point is the fact that the HelloWorld.h file contains the declara- tion of the C++ structure, built according to the specification in the XML file:
static const DDS_Long MAX_NAME_LEN = 64; static const DDS_Long MAX_MSG_LEN = 128; typedef struct HelloWorld
{
char* sender; /* maximum length = ((MAX_NAME_LEN)) */ char* message; /* maximum length = ((MAX_MSG_LEN)) */ DDS_Long count;
}HelloWorld;
2.2.3Build the Application
The example code is provided in C++, C#, and Java. The following instructions describe how to build it on Windows and
(RTI_CoreLibrariesAndUtilities_GettingStarted_EmbeddedSystemsAddendum.pdf) for instructions specific to these platforms.
C++ on Windows Systems:
1.In the Windows Explorer, go to <installation directory>\exam- ple\CPP\HelloWorld_xml_compiled and open the Microsoft Visual Studio solution file for your architecture. For example, the file for Visual Studio 2008 for
2.The Solution Configuration combo box in the toolbar indicates whether you are building debug or release executables; select Release. Select Build Solution from the Build menu.
Hello World using XML and Compiled Types
C++ on
1.From your command shell, change directory to <installation directory>/example/CPP/ HelloWorld_xml_compiled.
2.Type:
gmake
where <architecture> is one of the supported architectures (e.g., Make- file.i86Linux2.6gcc4.4.5). This command will build a release executable. To build a debug version instead, type:
gmake
2.2.4Run the Application
The previous step built two executables: HelloWorld_subscriber and HelloWorld_publisher. These applications should be in proper architecture subdirectory under the objs directory. For example, objs\i86Win32VS2008 in the Windows example cited below and objs/ i86Linux2.6gcc4.4.5 in the Linux example.
1.Start the subscribing application:
On a Windows system:
From your command shell, go to <installation directory>\exam- ple\CPP\HelloWorld_xml_compiled and type:
objs\<architecture>\HelloWorld_subscriber.exe
where <architecture> is the architecture you just built; see the contents of the objs directory to see the name of the architecture you built. For example, the Windows architecture name corresponding to
On a
From your command shell, change directory to <installation directory>/example/ CPP/HelloWorld_xml_ compiled and type:
objs/<architecture>/HelloWorld_subscriber
where <architecture> is the architecture you just built of the supported architectures; examine the contents of the objs directory to see the name of the architecture you built.
2. Start the publishing application:
On a Windows system:
From your command shell, go to <installation directory>\exam- ple\CPP\HelloWorld_xml_compiled and type:
objs\<architecture>\HelloWorld_publisher.exe
where <architecture> is the architecture you just built; see the contents of the objs directory to see the name of the architecture you built.
On a
From your command shell, change directory to <installation directory>/example/ CPP/HelloWorld_xml_ compiled and type:
objs/<architecture>/HelloWorld_publisher
Hello World using XML and Compiled Types
You should immediately see some messages on the publishing application showing that it is writing data and messages in the subscribing application indicating the data it receives. Do not worry about the contents of the messages. They are generated automatically for this example. The important thing is to understand how the application is defined which will be explained in the following
2.2.5Examine the XML Configuration Files Definition
This system is defined in the file USER_QOS_PROFILES.xml found in the directory <installa- tion directory>/example/CPP/HelloWorld_xml_compiled. Let’s look at its content and what are the elements defined to construct this scenario.
<dds
version="5.0.0">
<qos_profile name="DefaultProfile"> </qos_profile>
</qos_library>
<domain_library name="MyDomainLibrary" >
<domain name="HelloWorldDomain" domain_id="0">
<register_type name="HelloWorldType" kind="userGenerated"/> <topic name="HelloWorldTopic"
register_type_ref="HelloWorldType"> <topic_qos name="HelloWorld_qos"
base_name="qosLibrary::DefaultProfile"/> </topic>
</domain> </domain_library>
<participant_library name="MyParticipantLibrary"> <domain_participant name="PublicationParticipant"
domain_ref="MyDomainLibrary::HelloWorldDomain"> <publisher name="MyPublisher">
<data_writer name="HelloWorldWriter" topic_ref="HelloWorldTopic"/>
</publisher> </domain_participant>
<domain_participant name="SubscriptionParticipant" domain_ref="MyDomainLibrary::HelloWorldDomain"> <subscriber name="MySubscriber">
<data_reader name="HelloWorldReader" topic_ref="HelloWorldTopic">
<datareader_qos name="HelloWorld_reader_qos" base_name="qosLibrary::DefaultProfile"/>
</data_reader> </subscriber>
</domain_participant> </participant_library>
</dds>
The examination of this file reveals virtually the same information as was found in the HelloWorld_xml_dynamic example. This is no surprise as we are essentially trying to define the same system. Please revisit Examine the XML Configuration Files Definition (Section 2.1.3) for a
Hello World using XML and Compiled Types
description of what each section in the XML does.
Here we highlight the only two differences that can be seeing in the configuration file for the of the HelloWorld_xml_compiled example when compared with that of the
HelloWorld_xml_dynamic example:
❏The type definition “<types>” section does not appear in the configuration of the
HelloWorld_xml_compiled example.
❏The registration of the data types within the domain is slightly different
The
The registration of the
<register_type name="HelloWorldType" kind="userGenerated" />
This contrasts with what was used in the HelloWorld_xml_dynamic example:
<register_type name="HelloWorldType" kind="dynamicData" type_ref="HelloWorld" />
The modified syntax indicates a kind=“userGenerated” which means that the type will be defined via code generation and not use the DynamicData API. Since the type is defined via code generation there is no need to provide a reference to the
To sum it up, the XML configuration file is essentially the same except that the type definitions of the data types that will be compiled in are not present and that is indicated at the time the data type is registered in the domain by means of the attribute kind="userGenerated".
2.2.6Publisher Application
Open the file <installation directory>/examples/CPP/HelloWorld_publisher.cxx and look at the source code.
The logic of this simple application is contained in the publisher_main() function. The logic can be seen as composed of three parts:
❏Type registration (this step is new compared to the HelloWorld_xml_dynamic)
❏Entity creation
❏Use of the Entities
Type Registration: The first thing the application does is register the
/* type registration */
retcode = DDSTheParticipantFactory->register_type_support_exp( HelloWorldTypeSupport::register_type, "HelloWorldType");
The function register_type_support_exp() must be called for each
The function register_type_support_exp() takes as a parameter the TypeSupport function that defines the data type in compile code. In this case it is HelloWorldTypeSupport::register_type this function is declared in the HelloWorldSupport.h. However you cannot see it directly there because it is defined using macros. Instead you will find the line:
Hello World using XML and Compiled Types
DDS_TYPESUPPORT_CPP(HelloWorldTypeSupport, HelloWorld);
This line defines the HelloWorldTypeSupport::register_type() function.
In general if you include multiple
Entity Creation: The steps needed to create the entities are the same as for the HelloWorld_xml_dynamic example. The application first creates a DomainParticipant using the function create_participant_from_config_exp() this function takes the configuration name of the participant “MyParticipantLibrary::PublicationParticipant” which is the same name that was specified in the XML file. Note that the name in the XML file “PublicationParticipant” has been qualified with the name of the library it belongs to “MyParticipantLibrary”.
DDSDomainParticipant * participant =
"MyParticipantLibrary::PublicationParticipant", participant_name);
This single function call registers all the necessary data types and creates and the Topics and Entities that were specified in the XML file. In this simple case the participant only contains a publisher “MyPublisher” with a single DataWriter “HelloDataWriter”. However in more realis- tic scenarios this single call can create hundreds of entities (both readers and writers).
Use of the Entities: The remaining part of the function uses the entities that were created to per- form the logic of the program.
This example only needs to write data using the single data writer. So the application
HelloWorld_xml_dynamic example. Rather than the generic “DynamicDataWriter” used in the example here we use a DataWriter specific to the HelloWorld data type.
HelloWorldDataWriter * helloWorldWriter = HelloWorldDataWriter::narrow( participant->lookup_datawriter_by_name_exp( "MyPublisher::HelloWorldWriter"));
/* Create data */
HelloWorld * helloWorldData = HelloWorldTypeSupport::create_data();
/* Main loop */
for (count=0; (sample_count == 0) || (count < sample_count); ++count)
{
printf("Writing HelloWorld, count: %d\n", count);
/* Set the data fields */
Subscriber Application
retcode =
printf("write error %d\n", retcode); publisher_shutdown(participant); return
}
NDDSUtility::sleep(send_period);
}
Note that the data object helloWorldData can be manipulated directly as a
This “plain language object” API is both higher performance and friendlier to the programmer than the DynamicData API.
2.3Subscriber Application
Open the file <installation directory>/examples/CPP/HelloWorld_subscriber.cxx and look at the source code.
The logic of this simple application is in the subscriber_main() function. Similar to the publisher application the logic can be seen as composed of three parts:
❏Type registration (this step is new compared to the HelloWorld_xml_dynamic)
❏Entity creation
❏Use of the Entities
Type Registration: This step is identical to the one for the publisher application. The first thing the application does is register the
/* type registration */
retcode = DDSTheParticipantFactory->register_type_support_exp( HelloWorldTypeSupport::register_type, "HelloWorldType");
Please refer to the explanation of the publishing application for more details as this step us regardless of whether the application uses a type to publish or subscribe.
Entity Creation: The steps needed to create the entities are the same as for the HelloWorld_xml_dynamic example. The application first creates a DomainParticipant using the function create_participant_from_config_exp() this function takes the configuration name of the participant “MyParticipantLibrary::SubscriptionParticipant” which is the same name that was specified in the XML file. Note that the name in the XML file “SubscriptionParticipant” has been qualified with the name of the library it belongs to “MyParticipantLibrary”.
DDSDomainParticipant * participant =
"MyParticipantLibrary::SubscriptionParticipant", participant_name);
This single function call registers all the necessary
Subscriber Application
Use of the Entities: The remaining part of the function uses the entities that were created to per- form the logic of the program.
This example only needs to read data using the single DataReader So the application
HelloWorldDataReader * helloWorldReader = HelloWorldDataReader::narrow(
participant->lookup_datareader_by_name_exp( "MySubscriber::HelloWorldReader"));
To process the data, the application installs a Listener on the DataReader. The HelloWorldLis- tener, defined on the same file implements the DataReaderListener interface, which the DataReader uses to notify the application of relevant events, such as the reception of data.
/* Create a data reader listener */
HelloWorldListener *reader_listener = new HelloWorldListener();
/* set listener */
retcode =
The last part is the implementation of the listener functions. In this case we only implement the on_data_available() operation, which is called when data is received.
The on_data_available() function receives all the data into a sequence and then uses the Hello- WorldTypeSupport::print() function to print each data item received.
void HelloWorldListener::on_data_available(DDSDataReader* reader)
{
HelloWorldDataReader *helloWorldReader = NULL; HelloWorldSeq dataSeq;
DDS_SampleInfoSeq infoSeq;
DDS_ReturnCode_t retcode = DDS_RETCODE_ERROR; DDS_Long i = 0;
helloWorldReader = HelloWorldDataReader::narrow(reader);
retcode =
dataSeq, infoSeq, DDS_LENGTH_UNLIMITED,
DDS_ANY_SAMPLE_STATE, DDS_ANY_VIEW_STATE, DDS_ANY_INSTANCE_STATE);
for (i = 0; i < dataSeq.length(); ++i) { if (infoSeq[i].valid_data) {
HelloWorldTypeSupport::print_data(&dataSeq[i]);
}
}
retcode =
}
Note that the sequence received is of type HelloWorldSeq which contains the native plain lan- guage objects of type HelloWorld. This can be manipulated directly by the application. For example the fields can be dereferenced as shown in the code snippet below:
HelloWorld *helloWorldData = &dataSeq[i]; printf(“count= %s\n”,
Chapter 3 Using Connext Prototyper
RTI Connext Prototyper is a companion tool for use with the
On a Windows system:
From your command shell, go to <installation directory>\exam- ple\CPP\HelloWorld_xml_dynamic. Open two console windows.
In one window, type (all on one line):
$NDDSHOME\scripts\rtiddsprototyper
In the other window, type (all on one line):
$NDDSHOME\scripts\rtiddsprototyper
On a
From your command shell, go to <installation directory>/example/CPP/ HelloWorld_xml_dynamic. Open two console windows.
In one window, type (all on one line):
${NDDSHOME}/scripts/rtiddsprototyper
In the other window, type (all on one line):
${NDDSHOME}/scripts/rtiddsprototyper
You can run both of these on the same computer or on separate computers within the same (multicast enabled) network. You should immediately see the subscribing application receive and print the information from the publishing side.
For more information, please read the RTI Connext Prototyper Getting Started Guide (in
<NDDSHOME>/doc/pdf).
Chapter 4 Understanding
Creation
Figure 4.1 depicts a Connext application built with the aid of both the Connext API and an XML configuration file. Using the XML configuration file in combination with the
The Entities defined in the XML configuration file can be created by a single call to the API. Once created, all Entities can be retrieved from application code using standard “lookup” opera- tions so they can be used to read and write data.
Figure 4.1 Using both Connext API and XML Configuration File to Develop an Application
Connext Application
Connext API
XML Configuration
File
4.1Important Points
❏Applications can instantiate a DomainParticipant from a participant configuration described in the XML Configuration file. All the Entities defined by such a participant configuration are created automatically as part of DomainParticipant creation. In addition, multiple participant configurations may be defined within a single XML configuration file.
❏All the Entities created from a participant configuration are automatically assigned an entity name. Entities can be retrieved via “lookup” operations specifying their name. Each Entity stores its own name in the QoS policies of the Entity so that they can be retrieved locally (via a lookup) up and communicated via discovery. This is described in
Loading XML Configuration Files
Creating and Retrieving Entities Configured in an XML File (Section 4.7).
❏An XML configuration file is not tied to the application that uses it. Different applications may run using the same configuration file. A single file may define multiple participant configurations. A single application can instantiate as many DomainParticipants as desired.
❏Changes in the XML configuration file do not require recompilation, even if Entities are added or removed, unless the logic that uses the Entities also needs to change.
4.2Loading XML Configuration Files
Connext loads its XML configuration from multiple locations. This section presents the various approaches, listed in load order.
The first three locations contain QoS Profiles (see Chapter 15 in the RTI Core Libraries and Utilities User's Manual) and may also contain Entity configurations.
❏$NDDSHOME/resource/qos_profiles_5.0.x/xml/NDDS_QOS_PROFILES.xml
This file contains the Connext default QoS values; it is loaded automatically if it exists. When present this is the first file loaded.
❏File specified in NDDS_QOS_PROFILES Environment Variable
The files (or XML strings) separated by semicolons referenced in this environment vari- able, if any, are loaded automatically. These files are loaded after the NDDS_QOS_PROFILES.xml and they are loaded in the order they appear listed in the environment variable.
❏<working directory>/USER_QOS_PROFILES.xml
This file is loaded automatically if it exists in the ‘working directory’ of the application, that is, the directory from which the application is run. This file is loaded last.
4.3XML Syntax and Validation
The configuration files uses XML format. Please see Examine the XML Configuration Files Defi- nition (Section 2.1.3) for an example XML file and a description of its contents.
4.3.1Validation at
Connext validates the input XML files using a
This is only a copy of the DTD that Connext uses. Changing this file has no effect unless you specify its path with the DOCTYPE tag, described below.
You can overwrite the
<!DOCTYPE dds SYSTEM "/local/usr/rti/dds/modified_rti_dds_profiles.dtd">
Accessing Entities Defined in XML Configuration from an Application
If you do not specify the DOCTYPE tag in the XML file, the
4.3.2Validation during Editing
Connext provides DTD and XSD files that describe the format of the XML content. We highly rec- ommend including a reference to the XSD in the XML file. This provides helpful features in code editors such as Visual Studio, Eclipse, or Netbeans, including validation and
To include a reference to the XSD file, use the noNamespaceSchemaLocation attribute inside the opening <dds> tag, as illustrated below (replace ‘5.0.x’ with the current version number):
<?xml version="1.0"
<dds
version="5.0.x">
You may use relative or absolute paths to the schema files. These files are provided as part of your distribution in the following location (replace 5.0.x with the current version number):
❏<Connext installation directory>/resource/qos_profiles_5.0.x/schema/ rti_dds_profiles.xsd
❏<Connext installation directory>/resource/qos_profiles_5.0.x/schema/ rti_dds_profiles.dtd
If you want to use the DTD for syntax validation instead of the XSD, use the <!DOCTYPE> tag. Note, however, that this validation is less strict and will offer far less help in terms of
<?xml version="1.0"
$NDDSHOME/resource/qos_profiles_5.0.x/schema/rti_dds_profiles.dtd"> <dds>
...
</dds>
4.4Accessing Entities Defined in XML Configuration from an Application
You can use the operations listed in Table 4.1 to retrieve and then use the Entities defined in your XML configuration files.
Table 4.1 Operations Intended for Use with
Working with… |
Reference |
||
|
|
|
|
|
|
|
|
|
create_participant_from_config |
||
DomainParticipantFactory |
lookup_participant_by_name |
||
|
|||
|
|
|
|
|
register_type_support |
||
|
|
|
|
|
|
XML Tags for Configuring Entities |
|
|
Table 4.1 Operations Intended for Use with |
|
|
|
||
|
|
|
|
|
|
|
Working with… |
|
Reference |
|
|
|
|
|
|
|
|
|
|
lookup_publisher_by_name |
|
|
|
|
DomainParticipant |
lookup_subscriber_by_name |
|
|
|
|
lookup_datawriter_by_name |
|
|
||
|
|
|
|
|
|
|
|
lookup_datareader_by_name |
|
|
|
|
|
|
|
|
|
|
Publisher |
lookup_datawriter_by_name |
|
|
|
|
|
|
|
|
|
|
Subscriber |
lookup_datareader_by_name |
|
|
|
|
|
|
|
||
|
|
|
|
|
|
4.5XML Tags for Configuring Entities
There are two
❏<domain_library>: Defines a collection of domains. A domain defines a global data- space where applications can publish and subscribe to data by referring to the same Topic name. Each domain within the domain library defines the Topics and associated data- types that can be used within that domain. Note that this list is not necessarily exhaus- tive. The participants defined within the <participant_library> might add Topics beyond the ones listed in the domain library.
❏<participant_library>: Defines a collection of DomainParticipants. A DomainParticipant provides the means for an application to join a domain. The DomainParticipant contains all the Entities needed to publish and subscribe data in the domain (Publishers, Subscrib- ers, DataWriters, DataReaders, etc.).
Figure 4.2 and Table 4.2 describe the top- |
Figure 4.2 |
level tags that are allowed within the root |
|
<dds> tag. |
|
Table 4.2
|
|
|
Number |
Tags within <dds> |
|
Description |
of Tags |
|
|
|
Allowed |
|
|
|
|
|
Specifies a domain library. Set of <domain> definitions. |
|
|
<domain_library> |
Attributes: |
0 or more |
|
|
name |
Domain library name |
|
|
|
|
|
|
|
|
XML Tags for Configuring Entities |
|
|
Table 4.2 |
|
|
|||
|
|
|
|
|
|
|
|
|
|
Number |
|
|
Tags within <dds> |
|
Description |
of Tags |
|
|
|
|
|
Allowed |
|
|
|
|
|
|
|
|
<participant_library> |
Specifies a participant library. Set of <domain_participant> definitions. |
0 or more |
|
|
|
|
|
|
||
|
name |
Participant library name |
|
||
|
|
|
|
||
|
|
|
|
|
|
|
|
Specifies a QoS library and profiles. |
|
|
|
|
<qos_library> |
The contents of this tag are specified in the same manner as for a Con- |
0 or more |
|
|
|
|
next QoS profile |
|
|
|
|
|
ties User’s Manual. |
|
|
|
|
|
|
|
|
|
|
<types> |
Defines types that can be used for dynamic data registered types. |
0 or 1 |
|
|
|
|
|
|
|
|
4.5.1 |
Domain Library |
|
|
|
|
A domain library provides a way to organize a |
Figure 4.3 |
Domain Library Tag |
|
set of domains that belongs to the same system. |
|||
|
|
||
A domain represents a data space where data |
|
|
|
can be shared by means of reading and writing |
|
|
|
the same Topics, each Topic having an associated |
|
|
|
|
|
||
specify Topics and their data types. |
|
|
Figure 4.3, Table 4.3, and Table 4.4 describe what tags can be in a <domain_library>.
❏The <register_type> tag specifies a type definition that will be registered in the
DomainParticipants whenever they spec- ify a Topic associated with that data type.
❏The <topic> tag specifies a Topic by asso- ciating it with a <register_type> that contains the type information.
In a domain, you can also specify the domain ID to which the DomainParticipant associated with this domain will be bound.
Table 4.3 Domain Library Tags
Tags within |
|
Description |
Number of |
|
<domain_library> |
|
tags allowed |
||
|
|
|||
|
|
|
|
|
|
|
|
|
|
|
Specifies a domain. |
|
|
|
|
Attributes: |
|
|
|
|
|
|
|
|
|
name |
Domain name |
|
|
<domain> |
|
|
1 or more |
|
domain_id (optional) |
Domain ID (default id=0) |
|||
|
|
|||
|
|
|
|
|
|
|
Base domain name. Specifies |
|
|
|
base_name (optional) |
another domain from which prop- |
|
|
|
|
erties will be inherited. |
|
|
|
|
|
|
Note that a domain may inherit from another “base domain” definition by using the base_name attribute. A domain that declares a “base domain” might still override some of the properties in the base domain. Overriding is done simply by including elements in the derived domain with the same name as in the base domain.
|
|
|
|
XML Tags for Configuring Entities |
||
Table 4.4 Domain Tags |
|
|
|
|
||
|
|
|
|
|
|
|
|
Tags within |
|
|
|
Number |
|
|
|
Description |
|
of tags |
|
|
|
<domain> |
|
|
|
||
|
|
|
|
allowed |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Specifies how a type is registered |
|
|
|
|
|
|
Attributes: |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Name used to refer to this registered type |
|
|
|
|
|
|
within the XML file. This is also the name |
|
|
|
|
|
name |
under which the type is registered with the |
|
|
|
|
<register_type> |
|
DomainParticipants unless |
overridden by the |
1 or more |
|
|
|
|
<registered_name> tag. |
|
|
|
|
|
kind |
Specifies whether the type is |
|
|
|
|
|
data or generated by the user. |
|
|
||
|
|
|
|
|
||
|
|
|
|
|
|
|
|
|
|
Reference (fully qualified name) to a defined |
|
|
|
|
|
type_ref (optional) |
type within <types>. Required when kind is |
|
|
|
|
|
|
dynamic data. |
|
|
|
|
|
|
|
|
|
|
|
|
Specifies a topic associating its |
|
|
||
|
|
Attributes: |
|
|
|
|
|
|
|
|
|
|
|
|
|
name |
Name of the topic if no <registered_name> is |
|
|
|
|
<topic> |
specified. |
|
1 or more |
|
|
|
|
|
|
|||
|
|
|
|
|
||
|
|
register_type_ref |
Reference (name) to a register_type within this |
|
|
|
|
|
domain with which this topic is associated. |
|
|
||
|
|
|
|
|
||
|
|
|
|
|
|
|
|
The <register_type> tag, described in Figure 4.4 and |
Figure 4.4 Register Type Tag |
||||
|
Table 4.5, determines how a type is registered by |
|
|
|
||
|
specifying the type definition and the name with |
|
|
|
||
|
which it is registered. |
|
|
|
|
|
Table 4.5 Register Type Tag
Tags within |
Description |
|
Number of tags allowed |
<register_type> |
|
||
|
|
|
|
|
|
|
|
|
|
|
|
<registered_name> |
Name with which the type is registered. |
0 or 1 |
|
|
|
|
|
The <topic> tag, |
described in Figure 4.5 and |
Figure 4.5 Topic Tag |
|
Table 4.6, describes a Topic by specifying the name and type of the Topic. It may also contain the QoS configuration for that Topic.
|
|
|
XML Tags for Configuring Entities |
|
Table 4.6 Topic Tag |
|
|
|
|
|
|
|
|
|
|
Tags within <topic > |
Description |
Number of tags allowed |
|
|
|
|
|
|
|
<registered_name> |
Name of the Topic. |
0 or 1 |
|
|
|
|
|
|
|
<topic_qos> |
Topic QoS configuration. |
0 or 1 |
|
|
|
|
|
|
Some elements may refer to already specified types and QoS tags. The definitions of these refer- enced tags may appear either in the same configuration file or in a different
If a QoS is not specified for an Entity, then the QoS will be set to a default value that is either the default configured in the XML files, or if such default does not exist, then the Connext QoS defaults. Please see Chapter 15 “Configuring QoS with XML” in the RTI Core Libraries and Utili- ties User’s Manual for additional details in configuring QoS via XML.
For example:
<struct name="MyType">
<member name="message" type="string"/> <member name="count" type="long"/>
</struct>
</types>
<domain_library name="MyDomainLibrary" > <domain name="MyDomain" domain_id="10">
<register_type name="MyRegisteredType" kind="dynamicData" type_ref="MyType"/>
<topic name="MyTopic" register_type_ref="MyType"> <topic_qos base_name="qosLibrary::DefaultProfile"/>
</topic>
</domain> </domain_library>
The above configuration defines a domain with name “MyDomain” and domain_id “10” con- taining a Topic called “MyTopic” with type “MyType” registered with the name “MyRegistered- Type”:
❏<register_type>: It defines the registration of a dynamic data type with name “MyRegis- teredType” and definition
❏<topic>: with name “MyTopic” and whose corresponding type is the one defined above with the name “MyRegisteredType” found within the same configuration. The Topic QoS configuration is the one defined by the profile “qosLibrary::Default- Profile”, which is defined in a different file.
Note that the DomainParticipant created from a configuration profile bound this domain will be crated with domain_id=10, unless the domain_id is overridden in the participant configuration.
|
|
XML Tags for Configuring Entities |
4.5.2 |
Participant Library |
|
|
A participant library provides a way to orga- |
Figure 4.6 Participant Library Tag |
|
nize a set of participants belonging to the same |
|
|
system. A participant configuration specifies all |
|
|
the entities that a DomainParticipant created |
|
|
from this configuration will contain. |
|
|
Figure 4.6, Table 4.7, and Table 4.8 shows the |
|
|
description of a <participant_library> and the |
|
|
tags it contains. |
|
|
A <domain_participant> can be associated |
|
|
with a domain where topics and their associ- |
|
|
ated types are already defined. The elements |
|
|
<register_type> and <topic> may also be |
|
|
defined in a |
|
|
way it is done in a <domain>. This makes it |
|
|
possible to add Topics, |
|
|
the ones defined in the domain, or alternatively |
|
|
redefine the elements that are already in the |
|
|
<domain>. |
|
|
A <domain_participant> is defined by specify- |
|
|
ing the set of Entities it contains. This is done |
|
|
using tags such as <publisher>, <subscriber>, <data_writer> and <data_reader>, which specify |
|
|
a Entity of their corresponding type. These Entities are created within the DomainParticipant |
|
|
instantiated from the configuration profile that contains the definitions. |
|
Table 4.7 Participant Library Tag
Tags within |
|
|
|
|
|
|
Number |
|
Description |
|
|
of Tags |
|||
<participant_library> |
|
|
|
||||
|
|
|
|
|
|
Allowed |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|||
|
|
|
|
|
|||
|
Specifies a participant configuration. |
|
|
|
|||
|
Attributes: |
|
|
|
|
|
|
|
|
|
|
|
|||
|
name |
|
Participant configuration name. |
|
|||
|
|
|
|
|
|||
|
|
|
Base participant name. It specifies |
|
|||
|
base_name (optional) |
|
another participant from which to |
|
|||
|
|
|
inherit the configuration. |
|
|
||
|
|
|
|
|
|||
<domain_participant> |
|
|
Reference (fully qualified name) to |
1 or more |
|||
domain_ref (optional) |
|
a defined <domain> in the domain |
|||||
|
|
|
library. |
|
|
|
|
|
|
|
|
|
|||
|
|
|
Domain ID. If specified, overrides |
|
|||
|
|
|
the id in the domain it refers to. |
|
|||
|
domain_id (optional) |
|
If no |
domain_id |
is |
specified |
|
|
|
directly or in the referenced |
|
||||
|
|
|
|
||||
|
|
|
domain |
then |
the |
default |
|
|
|
|
domain_id is 0. |
|
|
|
|
|
|
|
|
|
|
|
|
A <domain_participant> may inherit its configuration from another “base participant” specified using the base_name attribute. In this case, overriding applies to the base <domain_participant> as well as to the referred <domain>.
Note that in DataWriters always belong to a Publisher and DataReaders to a Subscriber. For this rea- son the <data_writer> and <data_reader> typically appear nested inside the corresponding <publisher> and <subscriber> tags. However, for convenience, it is possible to define
XML Tags for Configuring Entities
<data_writer> and <data_reader> tags directly under the <domain_participant> tag. In this case, the DataWriters and DataReaders are created inside the implicit Publisher and Subscriber, respectively.
Table 4.8 Domain Participant Tag
Tags within |
|
|
|
|
|
|
Number |
|
Description |
|
|
|
of Tags |
||
<domain_participant > |
|
|
|
|
|||
|
|
|
|
|
|
Allowed |
|
|
|
|
|
|
|
|
|
|
|
|
|||||
<register_type> |
Specifies how a type is registered. Same as within the |
0 or more |
|||||
|
<domain> tag |
|
|
|
|
|
|
<topic> |
Specifies a topic. Same as within the <domain> tag |
0 or more |
|||||
|
|
|
|
|
|
||
|
Specifies a Publisher configuration. |
|
|
|
|
||
|
Attributes: |
|
|
|
|
|
|
|
|
|
|
|
|||
<publisher> |
name |
|
Publisher configuration name. |
0 or more |
|||
|
|
|
|
|
|
||
|
|
|
Number of Publishers that are |
|
|||
|
multiplicity (optional) |
|
created with this configuration. |
|
|||
|
|
|
Default is 1. |
|
|
|
|
|
|
|
|
|
|
|
|
|
Specifies a Subscriber configuration. |
|
|
|
|
||
|
Attributes: |
|
|
|
|
|
|
|
|
|
|
|
|||
<subscriber> |
name |
|
Subscriber configuration name. |
0 or more |
|||
|
|
|
|
|
|
||
|
|
|
Number of Subscribers that are |
|
|||
|
multiplicity (optional) |
|
created with this configuration. |
|
|||
|
|
|
Default is 1. |
|
|
|
|
|
|
|
|
||||
|
Specifies a DataWriter configuration. The DataWriter will |
|
|||||
|
be created inside the implicit Publisher. |
|
|
|
|||
|
Attributes: |
|
|
|
|
|
|
|
|
|
|
|
|||
|
name |
|
DataWriter configuration name. |
|
|||
|
|
|
|
|
|
|
|
<data_writer> |
|
|
Reference |
(name) |
a |
<topic> |
0 or more |
|
topic_ref |
|
within the <domain> referenced |
|
|||
|
|
|
by its <participant> parent. |
|
|||
|
|
|
|
|
|||
|
|
|
Number of DataWriters that are |
|
|||
|
multiplicity (optional) |
|
created with this configuration. |
|
|||
|
|
|
Default is 1. |
|
|
|
|
|
|
|
|
||||
|
Specifies a data reader configuration. The DataReader |
|
|||||
|
will be created inside the implicit subscriber. |
|
|
|
|||
|
Attributes: |
|
|
|
|
|
|
|
|
|
|
|
|||
|
name |
|
Data reader configuration name. |
|
|||
|
|
|
|
|
|
|
|
<data_reader> |
|
|
Reference |
(name) |
a |
<topic> |
0 or more |
|
topic_ref |
|
within the <domain> referenced |
|
|||
|
|
|
by its <participant> parent. |
|
|||
|
|
|
|
|
|||
|
|
|
Number of DataReaders that are |
|
|||
|
multiplicity (optional) |
|
created with this configuration. |
|
|||
|
|
|
Default is 1. |
|
|
|
|
|
|
|
|
|
|
||
<participant_qos> |
DomainParticipant QoS configuration. |
|
|
0 or 1 |
|||
|
|
|
|
|
|
|
|
XML Tags for Configuring Entities
The <publisher>, <subscriber>, <data_writer>, and <data_reader> tags are described in Figure 4.7, Table 4.9, Table 4.10, Table 4.11 and Table 4.12.
Figure 4.7 Publisher and Subscriber Tags
The <publisher> tag defines by default a Publisher. It may contain a QoS configuration and a sev- eral DataWriters. Likewise, the <subscriber> tag defines by default a Subscriber. It may contain a QoS configuration and a several DataReaders.
Table 4.9 Publisher Tag
|
Tags within |
Description |
|
Number of |
|
<publisher > |
|
Tags Allowed |
|
|
|
|
||
|
|
|
|
|
|
|
|
|
|
|
<data_writer> |
Specifies a DataWriter configuration. Same as within the |
|
0 or more |
|
|
<participant> tag. |
|
|
|
<publisher_qos> |
Publisher QoS configuration. |
|
0 or 1 |
|
|
|
|
|
Table 4.10 |
Subscriber Tag |
|
|
|
|
|
|
|
|
|
Tags within |
Description |
|
Number of |
|
<subscriber> |
|
Tags Allowed |
|
|
|
|
||
|
|
|
|
|
|
<data_reader> |
Specifies a DataReader configuration. Same as within the |
|
0 or more |
|
|
<participant> tag. |
|
|
|
<subscriber_qos> |
Subscriber QoS configuration. |
|
0 or 1 |
|
|
|
|
|
Table 4.11 |
DataWriter Tag |
|
|
|
|
|
|
|
|
|
Tags within |
Description |
|
Number of |
|
<data_writer > |
|
Tags Allowed |
|
|
|
|
||
|
|
|
|
|
|
<datawriter_qos> |
DataWriter QoS configuration |
|
0 or 1 |
|
|
|
|
|
Table 4.12 |
DataReader Tags |
|
|
|
|
|
|
|
|
|
Tags within |
Description |
|
Number of |
|
<data_reader> |
|
Tags Allowed |
|
|
|
|
||
|
|
|
|
|
|
<datareader_qos> |
DataReader QoS configuration. |
|
0 or more |
|
|
|
|
|
|
|
|
XML Tags for Configuring Entities |
||
Table 4.12 DataReader Tags |
|
|
|
|
|
|
|
|
|
|
|
|
Tags within |
|
Description |
Number of |
|
|
<data_reader> |
|
Tags Allowed |
|
|
|
|
|
|
||
|
|
|
|
|
|
|
|
Enables the creation of DataReader with this configuration |
|
|
|
|
|
from a ContentFilteredTopic. |
|
|
|
|
|
Attributes: |
|
|
|
|
|
|
|
|
|
|
|
|
Name of the ContentFilteredTopic. The Con- |
|
|
|
<filter> |
name |
tentFilteredTopic will be associated with the |
0 or 1 |
|
|
same Topic referenced by the containing |
|
|||
|
|
|
|||
|
|
|
<data_reader> |
|
|
|
|
|
|
|
|
|
|
filter_kind |
Specifies which ContentFilter to use. It |
|
|
|
|
defaults to the builtin.sql filter. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The <filter> tag within a <data_reader> enables content filtering. It causes the corresponding DataReader to be created from a ContentFilteredTopic with the specified filter characteristics.
Table 4.13 Filter Tag
Tags within |
Description |
Number of |
|
<filter > |
Tags Allowed |
||
|
|||
|
|
|
|
<expression> |
Filter expression |
0 or 1 |
|
|
|
|
|
|
List of parameters. Parameters are specified using |
|
|
|
<param> tags. |
|
|
|
The maximum number of parameters is 100. |
|
|
<parameter_list> |
<parameter_list> |
0 or 1 |
|
|
<param>param_0</param> |
|
|
|
<param>param_1</param> |
|
|
|
... |
|
|
|
</parameter_list> |
|
|
|
|
|
For example:
<domain_participant name="MyParticipant" domain_ref="MyDomainLibrary::MyDomain">
<publisher name="MyPublisher">
<data_writer name="MyWriter" topic_ref="MyTopic"/> </publisher>
<subscriber name="MySubscriber">
<data_reader name="MyReader" topic_ref="MyTopic"> <filter name="MyFilter" kind="builtin.sql"> <expression> count > %0 </expression>
<parameter_list> <param>10<param>
</parameter_list> </filter>
</data_reader> </subscriber>
</domain_participant>
Names Assigned to Entities
The above configuration defines a <domain_participant> that is bound to the <domain> “MyDomain”.
A DomainParticipant created from this configuration will contain:
❏A Publisher which has a DataWriter created from the Topic “MyTopic”.
❏A Subscriber which has DataReader created from a ContentFilteredTopic whose related Topic, “MyTopic”, uses a SQL filter.
4.6Names Assigned to Entities
Each Entity configured in a XML file is given a unique name. This name is used to refer to them from other parts of the XML configuration and also to retrieve them at
In the context of
❏Configuration name: The name of a specific Entity’s configuration. It is given by the name attribute of the corresponding XML element.
❏Entity name: The actual name of the Entity within the
•DomainParticipants must be given their Entity names explicitly when they are cre- ated. It is one of the parameters to the create_participant_with_configuration() call.
•Whenever the attribute multiplicity is set to a value greater than one. This setting indicates that a set of Entities should be all from the same configuration. As each Entity must have a unique name the system will automatically append a number to the configuration name to obtain the Entity name. For example, if we specified a multiplicity of “N”, then for each index “i” between 0 and
Entity Name |
Index: i |
“configuration_name” 0
“configuration_name#i”
That is, the Entity name followed by the token “#” and an index.
For example:
<publisher name="MyPublisher">
<data_writer name="MyWriter" multiplicity="3" topic_ref="MyTopic"/>
</publisher>
For the above XML configuration, the name assignment is:
Configuration |
Entity |
Multiplicity |
Entity Names |
|
|
|
|
“MyPublisher” |
Publisher |
1 |
“MyPublisher” |
|
|
|
|
|
|
|
“MyWriter” |
“MyWriter” |
DataWriter |
3 |
“MyWriter#1” |
|
|
|
“MyWriter#2” |
|
|
|
|
Names Assigned to Entities
The entity name is stored by Connext using the EntityNameQosPolicy QoS policy for DomainPar- ticipants, DataWriters and DataReaders. The policy is represented by the following C structure:
Struct DDS_EntityNameQosPolicy { char * name;
char * role_name
}
The mapping is:
Field |
Value |
|
|
|
|
name |
Entity name |
|
|
role_name |
Configuration name |
|
|
For Publishers and Subscribers, the name is stored in the GroupDataQosPolicy. This is a tempo- rary situation because the EntityNameQosPolicy is not available for Publishers and Subscribers in the current release. This policy is represented by the following C structure:
Struct DDS_GroupDataQosPolicy { DDS_OctetSeq value;
}
The mapping is:
Field Value
value.buffer |
Entity name |
For example, for the following configuration:
<domain_participant name="MyParticipant" domain_ref="MyDomainLibrary::MyDomain">
<publisher name="MyPublisher">
<data_writer name="MyWriter" topic_ref="MyTopic"/> </publisher>
</domain_participant>
The corresponding QoS policies for each entity are:
Entity |
QoS Policy |
Field Values |
|
|
|
|
|
|
|
|
|
DomainParticipant |
EntityNameQosPolicy |
name = [participant_name] |
|
role_name = “MyParticipant” |
|||
|
|
||
|
|
|
|
Publisher |
GroupDataQosPolicy |
value.buffer = “MyPublisher” |
|
|
|
|
|
DataWriter |
EntityNameQosPolicy |
name = “MyWriter” |
|
role_name = “MyWriter” |
|||
|
|
||
|
|
|
Where [participant_name] represents the value of the participant entity name specified at cre- ation time.
4.6.1Referring to Entities and Other Elements within XML Files
Entities and other elements within the XML file are addressed using a hierarchical name that matches their declaration hierarchy. This is summarized in the table below.
The example above corresponds to a configuration such as the one following:
<dds
|
|
|
Names Assigned to Entities |
|
|
|
|
|
|
|
Entity or |
Hierarchical Name |
Example Use |
|
|
Element |
|
||
|
|
|
|
|
|
|
|
|
|
|
type |
[type_name] |
type_ref="MyType" |
|
|
|
|
|
|
|
qos |
[qos_library_name]::[qos_profile_name] |
base_name="qosLibrary::DefaultProfile" |
|
|
|
|
|
|
|
domain |
[domain_libary_name]::[domain_name] |
domain_ref= |
|
|
"MyDomainLibrary::MyDomain" |
|
||
|
|
|
|
|
|
|
|
|
|
|
|
[participant_library_name]:: |
base_name= |
|
|
participant |
”MyParticipantLibrary::PublicationPar- |
|
|
|
[participant_name] |
|
||
|
|
ticipant” |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
[topic_name] |
|
|
|
topic |
Must be defined within the scope of the |
topic_ref="MyTopic" |
|
|
|
Domain or the Participant that refer to it |
|
|
|
|
|
|
|
|
|
[subscriber_name] |
|
|
|
publisher |
Must be defined within the scope of the |
base_name=”MyPublisher” |
|
|
|
Participant that refers to it |
|
|
|
|
|
|
|
|
|
[subscriber_name] |
|
|
|
subscriber |
Must be defined within the scope of the |
base_name=”MySubscriber” |
|
|
|
Participant that refers to it |
|
|
|
|
|
|
|
|
|
[publisher_name]::[datawriter_name] |
|
|
|
data_writer |
If addressing from within the same Pub- |
base_name=”MyPublisher::MyWriter” |
|
|
lisher the “publisher_name::” prefix may |
base_name=”MyWriter” |
|
|
|
|
|
||
|
|
be omitted |
|
|
|
|
|
|
|
|
|
[subscriber_name]::[datareader_name] |
|
|
|
data_reader |
If addressing from within the same Sub- |
base_name=”MySubscriber::MyReader” |
|
|
scriber the “subscriber_name::” prefix |
base_name=”MyReader” |
|
|
|
|
|
||
|
|
may be omitted |
|
|
|
|
|
|
|
|
version="5.0.x"> |
|
|
|
<types>
<struct name="MyType">
<member name="mylong" type="long"/> </struct>
</types>
<domain_library name="MyDomainLibrary" > <domain name="MyDomain" domain_id="0">
<register_type name="MyRegisteredType" kind="dynamicData" type_ref="MyType" />
<topic name="MyTopic" register_type_ref="MyRegisteredType"/>
</domain> </domain_library>
<participant_library name="MyParticipantLibrary">
<domain_participant name="MyParticipant" domain_ref="MyDomainLibrary::MyDomain">
<publisher name="MyPublisher">
<data_writer name="MyWriter" topic_ref="MyTopic"/> </publisher>
Creating and Retrieving Entities Configured in an XML File
<subscriber name="MySubscriber">
<data_reader name="MyReader" topic_ref="MyTopic"/> </subscriber>
</domain_participant> </participant_library>
</dds>
4.7Creating and Retrieving Entities Configured in an XML File
There are two kinds of operations that affect Entities configured in an XML file:
❏Create the defined entities. Only the operation create_participant_from_config() in the DomainParticipantFactory triggers the creation of a DomainParticipant and all its con- tained Entities given a configuration name.
❏Retrieve the defined entities: After creation, you can retrieve the defined Entities by using the lookup_by_name() operations available in the DomainParticipantFactory,
DomainParticipant, Publisher and Subscriber.
4.7.1Creating and Retrieving a DomainParticipant Configured in an XML File
To create a DomainParticipant from a configuration profile in XML, use the function create_participant_from_config(), which receives the configuration name and the participant name, and creates all the entities defined by that configuration.
For example:
<participant_library = “MyLibrary”> <domain_participant name="MyParticipant"
domain_ref="MyDomainLibrary::MyDomain" domain_id="1>
...
</domain_participant> </participant_library>
Given the above configuration, a DomainParticipant is created as follows:
DDSDomainParticipant * participant =
“MyLibrary::MyParticipant”,
“ExampleParticipantName”);
if (participant == NULL) { //handle error
}
The DomainParticipant is bound to the domain_id specified in either the <domain_participant>
Once it is created, it can be retrieved at any other place in your program as follows:
participant = DDSTheParticipantFactory->lookup_participant_by_name( “ExampleParticipantName”);
if (participant == NULL) { //handle error
}
Creating and Retrieving Entities Configured in an XML File
4.7.2Creating and Retrieving Publishers and Subscribers
Publishers and Subscribers configured in XML are created automatically when a DomainPartici- pant is created from the <domain_participant> that contains the <publisher> and <subscriber> configurations.
Given the following example:
<domain_participant name="MyParticipant" domain_ref="MyDomainLibrary::MyDomain">
<publisher name="MyPublisher" multiplicity="2">
...
</publisher>
<subscriber name="MySubscriber">
...
</subscriber> </domain_participant>
Once a DomainParticipant is created as explained in Creating and Retrieving a DomainPartici- pant Configured in an XML File (Section 4.7.1), Publishers and Subscribers can be retrieved from the created DomainParticipant using their name as follows:
DDSPublisher * publisher =
if (publisher == NULL) { //handle error
}
DDSPublisher * publisher_1 =
if (publisher == NULL) { //handle error
}
DDSSubscriber * subscriber =
if (subscriber == NULL) { //handle error
}
4.7.3Creating and Retrieving DataWriters and DataReaders
DataWriters and DataReaders configured in XML are created automatically when a DomainPartic- ipant is created from the <domain_participant> that contains the <data_writer> and <data_reader> configurations.
Given the following example:
<domain_participant name="MyParticipant" domain_ref="MyDomainLibrary::MyDomain">
<publisher name="MyPublisher">
<data_writer name="MyWriter" topic_ref="MyTopic"/> </publisher>
<subscriber name="MySubscriber">
<data_reader name="MyReader" topic_ref="MyTopic"/> </subscriber>
</domain_participant>
Creating and Retrieving Entities Configured in an XML File
Once a DomainParticipant is created as explained in Section 4.7.1, DataWriters and DataReaders can be retrieved from the created DomainParticipant using their
DDSDataWriter * dataWriter =
if (dataWriter == NULL) { //handle error
}
DDSDataReader * dataReader =
if (dataReader == NULL) { //handle error
}
Or from the created Publisher and Subscriber using their ‘unqualified’ name as shown below:
DDSDataWriter * dataWriter =
if (dataWriter == NULL) { //handle error
}
DDSDataReader * dataReader =
4.7.4Creating Content Filters
To use a content filter, modify the “SubscriptionParticipant” configuration to look like this:
<participant_library name="MyParticipantLibrary">
...
<domain_participant name="SubscriptionParticipantWithFilter" domain_ref="MyDomainLibrary::HelloWorldDomain">
<subscriber name="subscriber">
<data_reader name="HelloWorldReader" topic_ref="HelloWorldTopic">
<datareader_qos name="HelloWorld_reader_qos" base_name="qosLibrary::DefaultProfile"/>
<filter name="HelloWorldTopic" kind="builtin.sql">
<expression>count> count < 20 </expression> </filter>
</data_reader> </subscriber>
</domain_participant> </participant_library>
It adds a SQL content filter, which only accepts samples with the field count greater than two.
Creating and Retrieving Entities Configured in an XML File
Now run the HelloWorld_subscriber application without recompiling and check that it only receives data when counter less than 20 as expected.
4.7.5Using
If a
The definition of this function is given by:
typdef DDS_ReturnCode_t (*DomainParticipantFactory_RegisterTypeFunction) (DDSDomainParticipant * participant,
const char * type_name);
This “register type function” should be generated using the rtiddsgen
For example, the following XML snippet defines a data type registered under the name MyType with a TypeSupport that is
<domain name="MyDomain" domain_id="13">
<register_type name="MyType" kind="userGenerated"/>
...
</domain>
Continuing the example above, assume that the structure of "MyType" is described in the IDL file MyType.idl. Also assume that you are using the C++ language API and you have already run rtiddsgen and generated the
MyTypeSupport::register_type() operation with the type name MyType by calling DDSThePa-
DomainParticipant as shown in the C++ snippet below:
DDS_ReturnCode_t * retCode =
FooTypeSupport::register_type, "MyType"); if (retCode != DDS_RETCODE_OK) {
//handle error
}
You can find an example of using a