RTI Connext C++ API

Version 5.0.0

Generated by Doxygen 1.5.5

Mon Aug 13 09:00:30 2012

Contents

1 RTI Connext 1

1.1 Feedback and Support for this Release. . . . . . . . . . . . . . . . 1

1.2 Available Documentation. . . . . . . . . . . . . . . . . . . . . . . 2

2 Module Index 5

2.1 Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3 Class Index 9

3.1 Class Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

4 Class Index 15

4.1 Class List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

5 Module Documentation 29

5.1 Clock Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

5.2 Domain Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

5.3 DomainParticipantFactory . . . . . . . . . . . . . . . . . . . . . . 34

5.4 DomainParticipants . . . . . . . . . . . . . . . . . . . . . . . . . 37

5.5 Built-in Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

5.6 Topic Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

5.7 Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

5.8 User Data Type Support . . . . . . . . . . . . . . . . . . . . . . . 51

5.9 Type Code Support . . . . . . . . . . . . . . . . . . . . . . . . . 56

5.10 Built-in Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

ii CONTENTS

5.11 Dynamic Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

5.12 Publication Mo dule . . . . . . . . . . . . . . . . . . . . . . . . . . 82

5.13 Publishers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

5.14 Data Writers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

5.15 Flow Controllers . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

5.16 Subscription Mo dule . . . . . . . . . . . . . . . . . . . . . . . . . 95

5.17 Subscribers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

5.18 DataReaders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

5.19 Read Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

5.20 Query Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

5.21 Data Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

5.22 Sample States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

5.23 View States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

5.24 Instance States . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

5.25 Infrastructure Module . . . . . . . . . . . . . . . . . . . . . . . . 118

5.26 Built-in Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . 120

5.27 Multi-channel DataWriters . . . . . . . . . . . . . . . . . . . . . 122

5.28 Pluggable Transports . . . . . . . . . . . . . . . . . . . . . . . . . 124

5.29 Using Transport Plugins . . . . . . . . . . . . . . . . . . . . . . . 130

5.30 Built-in Transport Plugins . . . . . . . . . . . . . . . . . . . . . . 136

5.31 Conﬁguration Utilities . . . . . . . . . . . . . . . . . . . . . . . . 138

5.32 Unsupported Utilities . . . . . . . . . . . . . . . . . . . . . . . . 143

5.33 Durability and Persistence . . . . . . . . . . . . . . . . . . . . . . 144

5.34 System Properties . . . . . . . . . . . . . . . . . . . . . . . . . . 150

5.35 Conﬁguring QoS Proﬁles with XML . . . . . . . . . . . . . . . . 151

5.36 Publication Example . . . . . . . . . . . . . . . . . . . . . . . . . 154

5.37 Subscription Example . . . . . . . . . . . . . . . . . . . . . . . . 155

5.38 Participant Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 156

5.39 Topic Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

5.40 FlowController Use Cases . . . . . . . . . . . . . . . . . . . . . . 161

5.41 Publisher Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . 165

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

CONTENTS iii

5.42 DataWriter Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 166

5.43 Subscriber Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . 168

5.44 DataReader Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 172

5.45 Entity Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

5.46 Waitset Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . 179

5.47 Transport Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . 181

5.48 Filter Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

5.49 Creating Custom Content Filters . . . . . . . . . . . . . . . . . . 191

5.50 Large Data Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 195

5.51 Documentation Roadmap . . . . . . . . . . . . . . . . . . . . . . 197

5.52 Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

5.53 Using DDS:: Namespace . . . . . . . . . . . . . . . . . . . . . . . 201

5.54 DDS API R eference . . . . . . . . . . . . . . . . . . . . . . . . . 203

5.55 Queries and Filters Syntax . . . . . . . . . . . . . . . . . . . . . . 208

5.56 RTI Connext API Reference . . . . . . . . . . . . . . . . . . . . . 216

5.57 Programming How- To’s . . . . . . . . . . . . . . . . . . . . . . . 217

5.58 Programming Tools . . . . . . . . . . . . . . . . . . . . . . . . . . 219

5.59 rtiddsgen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

5.60 rtiddsping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

5.61 rtiddsspy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

5.62 Class Id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

5.63 Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

5.64 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

5.65 Shared Memory Transport . . . . . . . . . . . . . . . . . . . . . . 257

5.66 UDPv4 Transport . . . . . . . . . . . . . . . . . . . . . . . . . . 265

5.67 UDPv6 Transport . . . . . . . . . . . . . . . . . . . . . . . . . . 275

5.68 Participant Built-in Topics . . . . . . . . . . . . . . . . . . . . . 285

5.69 Topic Built-in Topics . . . . . . . . . . . . . . . . . . . . . . . . . 287

5.70 Publication Built-in Topics . . . . . . . . . . . . . . . . . . . . . 289

5.71 Subscription Built-in Topics . . . . . . . . . . . . . . . . . . . . . 291

5.72 String Built-in Type . . . . . . . . . . . . . . . . . . . . . . . . . 293

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

iv CONTENTS

5.73 KeyedString Built-in Type . . . . . . . . . . . . . . . . . . . . . . 294

5.74 Octets Built-in Type . . . . . . . . . . . . . . . . . . . . . . . . . 295

5.75 KeyedOctets Built-in Type . . . . . . . . . . . . . . . . . . . . . 296

5.76 DDS-Speciﬁc Primitive Types . . . . . . . . . . . . . . . . . . . . 297

5.77 Time Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

5.78 GUID Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

5.79 Sequence Number Support . . . . . . . . . . . . . . . . . . . . . . 310

5.80 Exception Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

5.81 Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

5.82 Status Kinds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

5.83 Thread Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

5.84 QoS Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

5.85 USER DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

5.86 TOPIC DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

5.87 GROUP DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

5.88 DURABILITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

5.89 PRESENTATION . . . . . . . . . . . . . . . . . . . . . . . . . . 351

5.90 DEADLINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

5.91 LATENCY BUDGET . . . . . . . . . . . . . . . . . . . . . . . . 354

5.92 OWNERSHIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

5.93 OWNERSHIP STRENGTH . . . . . . . . . . . . . . . . . . . . . 357

5.94 LIVELINESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

5.95 TIME BASED FILTER . . . . . . . . . . . . . . . . . . . . . . . 360

5.96 PARTITION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

5.97 RELIABILITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362

5.98 DESTINATION ORDER . . . . . . . . . . . . . . . . . . . . . . 365

5.99 HISTORY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367

5.100DURABILITY SERVICE . . . . . . . . . . . . . . . . . . . . . . 370

5.101RESOURCE LIMITS . . . . . . . . . . . . . . . . . . . . . . . . 371

5.102TRANSPORT PRIORITY . . . . . . . . . . . . . . . . . . . . . 373

5.103LIFESPAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

CONTENTS v

5.104WRITER DATA LIFECYCLE . . . . . . . . . . . . . . . . . . . 375

5.105READER DATA LIFECYCLE . . . . . . . . . . . . . . . . . . . 376

5.106ENTITY FACTORY . . . . . . . . . . . . . . . . . . . . . . . . . 377

5.107Extended Qos Support . . . . . . . . . . . . . . . . . . . . . . . . 378

5.108Unicast Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . 379

5.109Multicast Settings . . . . . . . . . . . . . . . . . . . . . . . . . . 380

5.110Multicast Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . 381

5.111TRANSPORT SELECTION . . . . . . . . . . . . . . . . . . . . 382

5.112TRANSPORT UNICAST . . . . . . . . . . . . . . . . . . . . . . 383

5.113TRANSPORT MULTICAST . . . . . . . . . . . . . . . . . . . . 384

5.114TRANSPORT MULTICAST MAPPING . . . . . . . . . . . . . 386

5.115DISCOVERY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387

5.116NDDS DISCOVERY PEERS . . . . . . . . . . . . . . . . . . . . 388

5.117TRANSPORT BUILTIN . . . . . . . . . . . . . . . . . . . . . . . 396

5.118WIRE PROTOCOL . . . . . . . . . . . . . . . . . . . . . . . . . 400

5.119DATA READER RESOURCE LIMITS . . . . . . . . . . . . . . 407

5.120DATA WRITER RESOURCE LIMITS . . . . . . . . . . . . . . 409

5.121DATA READER PROTOCOL . . . . . . . . . . . . . . . . . . . 413

5.122DATA WRITER PROTOCOL . . . . . . . . . . . . . . . . . . . 414

5.123SYSTEM RESOURCE LIMITS . . . . . . . . . . . . . . . . . . . 415

5.124DOMAIN PARTICIPANT RESOURCE LIMITS . . . . . . . . . 416

5.125EVENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417

5.126DATABASE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418

5.127RECEIVER POOL . . . . . . . . . . . . . . . . . . . . . . . . . . 419

5.128PUBLISH MODE . . . . . . . . . . . . . . . . . . . . . . . . . . 420

5.129DISCOVERY CONFIG . . . . . . . . . . . . . . . . . . . . . . . 423

5.130ASYNCHRONOUS PUBLISHER . . . . . . . . . . . . . . . . . . 428

5.131TYPESUPPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . 429

5.132EXCLUSIVE AREA . . . . . . . . . . . . . . . . . . . . . . . . . 430

5.133BATCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431

5.134TYPE CONSISTENCY ENFORCEMENT . . . . . . . . . . . . 432

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

vi CONTENTS

5.135LOCATORFILTER . . . . . . . . . . . . . . . . . . . . . . . . . 434

5.136MULTICHANNEL . . . . . . . . . . . . . . . . . . . . . . . . . . 435

5.137PROPERTY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436

5.138AVAILABILITY . . . . . . . . . . . . . . . . . . . . . . . . . . . 442

5.139Entity Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443

5.140Conditions and WaitSets . . . . . . . . . . . . . . . . . . . . . . . 444

5.141ENTITY NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . 445

5.142PROFILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446

5.143WriteParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447

5.144LOGGING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450

5.145Octet Buﬀer Support . . . . . . . . . . . . . . . . . . . . . . . . . 451

5.146Sequence Support . . . . . . . . . . . . . . . . . . . . . . . . . . . 455

5.147String Supp ort . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456

6 Class Documentation 463

6.1 DDS AckResponseData t Struct Reference . . . . . . . . . . . . . 463

6.2 DDS AllocationSettings t Struct Reference . . . . . . . . . . . . 464

6.3 DDS AsynchronousPublisherQosPolicy Struct Reference . . . . . 466

6.4 DDS AvailabilityQosPolicy Struct Reference . . . . . . . . . . . . 471

6.5 DDS BatchQosPolicy Struct Reference . . . . . . . . . . . . . . . 476

6.6 DDS BooleanSeq Struct Reference . . . . . . . . . . . . . . . . . 480

6.7 DDS BuiltinTopicKey t Struct Reference . . . . . . . . . . . . . 481

6.8 DDS BuiltinTopicReaderResourceLimits t Struct Reference . . . 482

6.9 DDS ChannelSettings t Struct Reference . . . . . . . . . . . . . . 486

6.10 DDS ChannelSettingsSeq Struct Reference . . . . . . . . . . . . . 489

6.11 DDS CharSeq Struct Reference . . . . . . . . . . . . . . . . . . . 490

6.12 DDS ContentFilterProperty t Struct Reference . . . . . . . . . . 491

6.13 DDS Cookie t Struct Reference . . . . . . . . . . . . . . . . . . . 493

6.14 DDS CookieSeq Struct Reference . . . . . . . . . . . . . . . . . . 494

6.15 DDS DatabaseQosPolicy Struct Reference . . . . . . . . . . . . . 495

6.16 DDS DataReaderCacheStatus Struct Reference . . . . . . . . . . 500

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

CONTENTS vii

6.17 DDS DataReaderProtocolQosPolicy Struct Reference . . . . . . . 501

6.18 DDS DataReaderProtocolStatus Struct Reference . . . . . . . . . 505

6.19 DDS DataReaderQos Struct Reference . . . . . . . . . . . . . . . 515

6.20 DDS DataReaderResourceLimitsQosPolicy Struct Reference . . . 521

6.21 DDS DataWriterCacheStatus Struct Reference . . . . . . . . . . 534

6.22 DDS DataWriterProtocolQosPolicy Struct Reference . . . . . . . 535

6.23 DDS DataWriterProtocolStatus Struct Reference . . . . . . . . . 540

6.24 DDS DataWriterQos Struct Reference . . . . . . . . . . . . . . . 553

6.25 DDS DataWriterResourceLimitsQosPolicy Struct Reference . . . 560

6.26 DDS DeadlineQosPolicy Struct Reference . . . . . . . . . . . . . 567

6.27 DDS DestinationOrderQosPolicy Struct Re ference . . . . . . . . 570

6.28 DDS DiscoveryConﬁgQosPolicy Struct Reference . . . . . . . . . 573

6.29 DDS DiscoveryQosPolicy Struct Reference . . . . . . . . . . . . . 582

6.30 DDS DomainParticipantFactoryQos Struct Reference . . . . . . . 586

6.31 DDS DomainParticipantQos Struct Reference . . . . . . . . . . . 588

6.32 DDS DomainParticipantResourceLimitsQosPolicy Struct Refer-

ence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593

6.33 DDS DoubleSeq Struct Reference . . . . . . . . . . . . . . . . . . 613

6.34 DDS DurabilityQosPolicy Struct Reference . . . . . . . . . . . . 614

6.35 DDS DurabilityServiceQosPolicy Struct Reference . . . . . . . . 618

6.36 DDS Duration t Struct Reference . . . . . . . . . . . . . . . . . . 621

6.37 DDS DynamicData Struct Reference . . . . . . . . . . . . . . . . 622

6.38 DDS DynamicDataInfo Struct Reference . . . . . . . . . . . . . . 721

6.39 DDS DynamicDataMemberInfo Struct Reference . . . . . . . . . 722

6.40 DDS DynamicDataProp erty t Struct Reference . . . . . . . . . . 725

6.41 DDS DynamicDataSeq Struct Reference . . . . . . . . . . . . . . 727

6.42 DDS DynamicDataTypeProperty t Struct Reference . . . . . . . 728

6.43 DDS DynamicDataTypeSerializationProperty t Struct Reference 729

6.44 DDS Endp ointGroup t Struct Reference . . . . . . . . . . . . . . 731

6.45 DDS Endp ointGroupSeq Struct Reference . . . . . . . . . . . . . 732

6.46 DDS EntityFactoryQosPolicy Struct Reference . . . . . . . . . . 733

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

viii CONTENTS

6.47 DDS EntityNameQosPolicy Struct Reference . . . . . . . . . . . 735

6.48 DDS EnumMember Struct Reference . . . . . . . . . . . . . . . . 737

6.49 DDS EnumMemberSeq Struct Reference . . . . . . . . . . . . . . 738

6.50 DDS EventQosPolicy Struct Reference . . . . . . . . . . . . . . . 739

6.51 DDS ExclusiveAreaQosPolicy Struct Reference . . . . . . . . . . 742

6.52 DDS ExpressionProp erty Struct Reference . . . . . . . . . . . . . 745

6.53 DDS FactoryPluginSupport Struct Reference . . . . . . . . . . . 746

6.54 DDS FilterSampleInfo Struct Reference . . . . . . . . . . . . . . 747

6.55 DDS FloatSeq Struct Reference . . . . . . . . . . . . . . . . . . . 748

6.56 DDS FlowControllerProperty t Struct Reference . . . . . . . . . 749

6.57 DDS FlowControllerTokenBucketProperty t Struct R eference . . 751

6.58 DDS GroupDataQosPolicy Struct Re ference . . . . . . . . . . . . 755

6.59 DDS GUID t Struct Reference . . . . . . . . . . . . . . . . . . . 757

6.60 DDS HistoryQosPolicy Struct Reference . . . . . . . . . . . . . . 758

6.61 DDS InconsistentTopicStatus Struct Reference . . . . . . . . . . 762

6.62 DDS InstanceHandleSeq Struct Reference . . . . . . . . . . . . . 764

6.63 DDS Keye dOctets Struct Reference . . . . . . . . . . . . . . . . . 765

6.64 DDS Keye dOctetsSeq Struct Reference . . . . . . . . . . . . . . . 767

6.65 DDS Keye dString Struct Re ference . . . . . . . . . . . . . . . . . 768

6.66 DDS Keye dStringSeq Struct Reference . . . . . . . . . . . . . . . 770

6.67 DDS LatencyBudgetQosPolicy Struct Reference . . . . . . . . . . 771

6.68 DDS LifespanQosPolicy Struct Reference . . . . . . . . . . . . . 773

6.69 DDS LivelinessC hangedStatus Struct Reference . . . . . . . . . . 775

6.70 DDS LivelinessLos tStatus Struct Reference . . . . . . . . . . . . 777

6.71 DDS LivelinessQos Policy Struct Reference . . . . . . . . . . . . . 779

6.72 DDS Locator t Struct Reference . . . . . . . . . . . . . . . . . . 783

6.73 DDS LocatorFilter t Struct Reference . . . . . . . . . . . . . . . 785

6.74 DDS LocatorFilterQosPolicy Struct Reference . . . . . . . . . . . 787

6.75 DDS LocatorFilterSeq Struct Reference . . . . . . . . . . . . . . 789

6.76 DDS LocatorSeq Struct Reference . . . . . . . . . . . . . . . . . 790

6.77 DDS LoggingQosPolicy Struct Reference . . . . . . . . . . . . . . 791

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

CONTENTS ix

6.78 DDS LongDoubleSeq Struct Reference . . . . . . . . . . . . . . . 793

6.79 DDS LongLongSeq Struct Reference . . . . . . . . . . . . . . . . 794

6.80 DDS LongSeq Struct Reference . . . . . . . . . . . . . . . . . . . 795

6.81 DDS MultiChannelQosPolicy Struct Reference . . . . . . . . . . 796

6.82 DDS Octets Struct Reference . . . . . . . . . . . . . . . . . . . . 799

6.83 DDS OctetSeq Struct Reference . . . . . . . . . . . . . . . . . . . 801

6.84 DDS OctetsSeq Struct Reference . . . . . . . . . . . . . . . . . . 802

6.85 DDS OﬀeredDeadlineMissedStatus Struct Reference . . . . . . . 803

6.86 DDS OﬀeredIncompatibleQosStatus Struct Reference . . . . . . . 805

6.87 DDS OwnershipQosPolicy Struct Reference . . . . . . . . . . . . 807

6.88 DDS OwnershipStrengthQosPolicy Struct Reference . . . . . . . 814

6.89 DDS ParticipantBuiltinTopicData Struct Reference . . . . . . . . 816

6.90 DDS ParticipantBuiltinTopicDataSeq Struct Reference . . . . . . 819

6.91 DDS PartitionQosPolicy Struct Reference . . . . . . . . . . . . . 820

6.92 DDS PresentationQosPolicy Struct Reference . . . . . . . . . . . 823

6.93 DDS ProductVersion t Struct Reference . . . . . . . . . . . . . . 828

6.94 DDS ProﬁleQosPolicy Struct Reference . . . . . . . . . . . . . . 830

6.95 DDS Property t Struct Reference . . . . . . . . . . . . . . . . . . 833

6.96 DDS PropertyQosPolicy Struct Reference . . . . . . . . . . . . . 834

6.97 DDS PropertySeq Struct Reference . . . . . . . . . . . . . . . . . 837

6.98 DDS ProtocolVersion t Struct Reference . . . . . . . . . . . . . . 838

6.99 DDS PublicationBuiltinTopicData Struct Reference . . . . . . . 839

6.100DDS PublicationBuiltinTopicDataSeq Struct Reference . . . . . . 847

6.101DDS PublicationMatchedStatus Struct Reference . . . . . . . . . 848

6.102DDS PublisherQos Struct Reference . . . . . . . . . . . . . . . . 851

6.103DDS PublishMo deQosPolicy Struct Reference . . . . . . . . . . . 853

6.104DDS QosPolicyCount Struct Reference . . . . . . . . . . . . . . . 857

6.105DDS QosPolicyCountSeq Struct Reference . . . . . . . . . . . . . 858

6.106DDS ReaderDataLifecycleQosPolicy Struct Reference . . . . . . . 859

6.107DDS ReceiverPoolQosPolicy Struct Reference . . . . . . . . . . . 862

6.108DDS ReliabilityQosPolicy Struct Reference . . . . . . . . . . . . 865

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

x CONTENTS

6.109DDS ReliableReaderActivityChangedStatus Struct Re ference . . 869

6.110DDS ReliableWriterCacheChangedStatus Struct Reference . . . . 871

6.111DDS ReliableWriterCacheEventCount Struct Reference . . . . . 874

6.112DDS RequestedDeadlineMissedStatus Struct Reference . . . . . . 875

6.113DDS RequestedIncompatibleQosStatus Struct Reference . . . . . 877

6.114DDS ResourceLimitsQosPolicy Struct Reference . . . . . . . . . 879

6.115DDS RtpsRe liableReaderProtocol t Struct Reference . . . . . . . 884

6.116DDS RtpsRe liableWriterProtocol t Struct Reference . . . . . . . 889

6.117DDS RtpsWellKnownPorts t Struct R eference . . . . . . . . . . . 905

6.118DDS SampleIdentity t Struct Reference . . . . . . . . . . . . . . 911

6.119DDS SampleInfo Struct Reference . . . . . . . . . . . . . . . . . 912

6.120DDS SampleInfoSeq Struct Reference . . . . . . . . . . . . . . . 922

6.121DDS SampleLostStatus Struct Reference . . . . . . . . . . . . . . 923

6.122DDS SampleRejectedStatus Struct Reference . . . . . . . . . . . 925

6.123DDS SequenceNumber t Struct Reference . . . . . . . . . . . . . 927

6.124DDS ShortSeq Struct Reference . . . . . . . . . . . . . . . . . . . 928

6.125DDS StringSeq Struct Reference . . . . . . . . . . . . . . . . . . 929

6.126DDS StructMember Struct Reference . . . . . . . . . . . . . . . . 931

6.127DDS StructMemberSeq Struct Reference . . . . . . . . . . . . . . 933

6.128DDS Subscrib e rQos Struct Reference . . . . . . . . . . . . . . . . 934

6.129DDS SubscriptionBuiltinTopicData Struct Reference . . . . . . . 936

6.130DDS SubscriptionBuiltinTopicDataSeq Struct Reference . . . . . 944

6.131DDS SubscriptionMatchedStatus Struct Reference . . . . . . . . 945

6.132DDS SystemResourceLimitsQosPolicy Struct Reference . . . . . 948

6.133DDS ThreadSettings t Struct Reference . . . . . . . . . . . . . . 950

6.134DDS Time t Struct Reference . . . . . . . . . . . . . . . . . . . . 953

6.135DDS TimeBasedFilterQosPolicy Struct Reference . . . . . . . . . 954

6.136DDS TopicBuiltinTopicData Struct Reference . . . . . . . . . . . 958

6.137DDS TopicBuiltinTopicDataSeq Struct Reference . . . . . . . . . 962

6.138DDS TopicDataQosPolicy Struct Reference . . . . . . . . . . . . 963

6.139DDS TopicQos Struct Reference . . . . . . . . . . . . . . . . . . 965

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

CONTENTS xi

6.140DDS TransportBuiltinQosPolicy Struct Reference . . . . . . . . . 969

6.141DDS TransportMulticastMapping t Struct Reference . . . . . . . 971

6.142DDS TransportMulticastMappingFunction t Struct Reference . . 973

6.143DDS TransportMulticastMappingQosPolicy Struct Reference . . 975

6.144DDS TransportMulticastMappingSeq Struct Reference . . . . . . 977

6.145DDS TransportMulticastQosPolicy Struct Reference . . . . . . . 978

6.146DDS TransportMulticastSettings t Struct Reference . . . . . . . 980

6.147DDS TransportMulticastSettingsSeq Struct Reference . . . . . . 982

6.148DDS TransportPriorityQosPolicy Struct Reference . . . . . . . . 983

6.149DDS TransportSelectionQosPolicy Struct Reference . . . . . . . . 985

6.150DDS TransportUnicastQosPolicy Struct Reference . . . . . . . . 987

6.151DDS TransportUnicastSettings t Struct Reference . . . . . . . . 989

6.152DDS TransportUnicastSettingsSeq Struct Re ference . . . . . . . 991

6.153DDS TypeCode Struct Reference . . . . . . . . . . . . . . . . . . 992

6.154DDS TypeCodeFactory Struct Reference . . . . . . . . . . . . . . 1022

6.155DDS TypeConsistencyEnforcementQosPolicy Struct Reference . 1038

6.156DDS TypeSupportQosPolicy Struct Reference . . . . . . . . . . . 1040

6.157DDS UnionMember Struct Reference . . . . . . . . . . . . . . . . 1042

6.158DDS UnionMemberSeq Struct Reference . . . . . . . . . . . . . . 1044

6.159DDS UnsignedLongLongSeq Struct Reference . . . . . . . . . . . 1045

6.160DDS UnsignedLongSeq Struct Reference . . . . . . . . . . . . . . 1046

6.161DDS UnsignedShortSeq Struct Reference . . . . . . . . . . . . . 1047

6.162DDS UserDataQosPolicy Struct Reference . . . . . . . . . . . . . 1048

6.163DDS ValueMember Struct Reference . . . . . . . . . . . . . . . . 1050

6.164DDS ValueMemberSeq Struct Reference . . . . . . . . . . . . . . 1052

6.165DDS VendorId t Struct Reference . . . . . . . . . . . . . . . . . . 1053

6.166DDS VirtualSubscriptionBuiltinTopicData Struct Reference . . . 1054

6.167DDS VirtualSubscriptionBuiltinTopicDataSeq Struct Reference . 1055

6.168DDS WaitSetProperty t Struct Reference . . . . . . . . . . . . . 1056

6.169DDS WcharSeq Struct Reference . . . . . . . . . . . . . . . . . . 1058

6.170DDS WireProto c olQosPolicy Struct Reference . . . . . . . . . . . 1059

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

xii CONTENTS

6.171DDS WriteParams t Struct Reference . . . . . . . . . . . . . . . 1067

6.172DDS WriterDataLifecycleQosPolicy Struct Reference . . . . . . . 1071

6.173DDS WstringSeq Struct Reference . . . . . . . . . . . . . . . . . 1074

6.174DDSCondition Class Reference . . . . . . . . . . . . . . . . . . . 1075

6.175DDSConditionSeq Struct Reference . . . . . . . . . . . . . . . . . 1076

6.176DDSContentFilter Class Reference . . . . . . . . . . . . . . . . . 1077

6.177DDSContentFilteredTopic Class Reference . . . . . . . . . . . . . 1081

6.178DDSDataReader Class Reference . . . . . . . . . . . . . . . . . . 1087

6.179DDSDataReaderListener Class Reference . . . . . . . . . . . . . 1108

6.180DDSDataReaderSeq Class Reference . . . . . . . . . . . . . . . . 1112

6.181DDSDataWriter Class Reference . . . . . . . . . . . . . . . . . . 1113

6.182DDSDataWriterListener Class Reference . . . . . . . . . . . . . . 1133

6.183DDSDomainEntity Class Reference . . . . . . . . . . . . . . . . . 1138

6.184DDSDomainParticipant Class Reference . . . . . . . . . . . . . . 1139

6.185DDSDomainParticipantFactory Class Reference . . . . . . . . . . 1216

6.186DDSDomainParticipantListener Class Reference . . . . . . . . . 1243

6.187DDSDynamicDataReader Class Reference . . . . . . . . . . . . . 1245

6.188DDSDynamicDataTypeSupport Class Reference . . . . . . . . . . 1246

6.189DDSDynamicDataWriter Class Reference . . . . . . . . . . . . . 1252

6.190DDSEntity Class Reference . . . . . . . . . . . . . . . . . . . . . 1253

6.191DDSFlowController Class Reference . . . . . . . . . . . . . . . . 1259

6.192DDSGuardCondition Class Reference . . . . . . . . . . . . . . . . 1263

6.193DDSKeyedOctetsDataReader Class Reference . . . . . . . . . . . 1265

6.194DDSKeyedOctetsDataWriter Class Reference . . . . . . . . . . . 1276

6.195DDSKeyedOctetsTypeSupport Class Reference . . . . . . . . . . 1289

6.196DDSKeyedStringDataReader Class Reference . . . . . . . . . . . 1293

6.197DDSKeyedStringDataWriter Class Reference . . . . . . . . . . . 1304

6.198DDSKeyedStringTypeSupport Class Reference . . . . . . . . . . 1314

6.199DDSListener Class Reference . . . . . . . . . . . . . . . . . . . . 1318

6.200DDSMultiTopic Class Reference . . . . . . . . . . . . . . . . . . . 1322

6.201DDSOctetsDataReader Class Reference . . . . . . . . . . . . . . 1326

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

CONTENTS xiii

6.202DDSOctetsDataWriter Class Reference . . . . . . . . . . . . . . . 1331

6.203DDSOctetsTypeSupport Class Reference . . . . . . . . . . . . . . 1337

6.204DDSParticipantBuiltinTopicDataDataReader Class Reference . . 1341

6.205DDSParticipantBuiltinTopicDataTypeSupport Class Reference . 1342

6.206DDSPropertyQosPolicyHelper Class Reference . . . . . . . . . . 1343

6.207DDSPublicationBuiltinTopicDataDataReader Class Reference . . 1344

6.208DDSPublicationBuiltinTopicDataTypeSupport Class Reference . 1345

6.209DDSPublisher Class Reference . . . . . . . . . . . . . . . . . . . 1346

6.210DDSPublisherListener Class Refere nce . . . . . . . . . . . . . . . 1370

6.211DDSPublisherSeq Class Reference . . . . . . . . . . . . . . . . . 1371

6.212DDSQueryCondition Class Reference . . . . . . . . . . . . . . . . 1372

6.213DDSReadCondition Class Reference . . . . . . . . . . . . . . . . 1374

6.214DDSStatusCondition Class Reference . . . . . . . . . . . . . . . . 1376

6.215DDSStringDataReader Class Reference . . . . . . . . . . . . . . . 1379

6.216DDSStringDataWriter Class Reference . . . . . . . . . . . . . . . 1383

6.217DDSStringTypeSupport Class Reference . . . . . . . . . . . . . . 1386

6.218DDSSubscriber Class Reference . . . . . . . . . . . . . . . . . . . 1390

6.219DDSSubscriberListener Class Reference . . . . . . . . . . . . . . 1414

6.220DDSSubscriberSeq Class Reference . . . . . . . . . . . . . . . . . 1416

6.221DDSSubscriptionBuiltinTopicDataDataReader Class Reference . 1417

6.222DDSSubscriptionBuiltinTopicDataTypeSupport Class Reference 1418

6.223DDSTopic Class Reference . . . . . . . . . . . . . . . . . . . . . . 1419

6.224DDSTopicBuiltinTopicDataDataReader Class Reference . . . . . 1425

6.225DDSTopicBuiltinTopicDataTypeSupport Class Reference . . . . 1426

6.226DDSTopicDescription Class Reference . . . . . . . . . . . . . . . 1427

6.227DDSTopicListener Class Reference . . . . . . . . . . . . . . . . . 1430

6.228DDSTypeSupport Class Reference . . . . . . . . . . . . . . . . . 1432

6.229DDSWaitSet Class Reference . . . . . . . . . . . . . . . . . . . . 1433

6.230DDSWriterContentFilter Class Reference . . . . . . . . . . . . . 1441

6.231Foo Struct Reference . . . . . . . . . . . . . . . . . . . . . . . . . 1443

6.232FooDataReader Struct Reference . . . . . . . . . . . . . . . . . . 1444

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

xiv CONTENTS

6.233FooDataWriter Struct Reference . . . . . . . . . . . . . . . . . . 1475

6.234FooSeq Struct Reference . . . . . . . . . . . . . . . . . . . . . . . 1494

6.235FooTypeSupport Struct Reference . . . . . . . . . . . . . . . . . 1509

6.236NDDS Conﬁg LibraryVersion t Struct Reference . . . . . . . . . 1518

6.237NDDS Conﬁg LogMessage Struct Reference . . . . . . . . . . . . 1520

6.238NDDS Transport Address t Struct Reference . . . . . . . . . . . 1521

6.239NDDS Transport Property t Struct Reference . . . . . . . . . . . 1522

6.240NDDS Transport Shmem Property t Struct Reference . . . . . . 1530

6.241NDDS Transport UDPv4 Property t Struct Reference . . . . . . 1533

6.242NDDS Transport UDPv6 Property t Struct Reference . . . . . . 1542

6.243NDDSConﬁgLogger Class Reference . . . . . . . . . . . . . . . . 1550

6.244NDDSConﬁgLoggerDevice Class Reference . . . . . . . . . . . . . 1555

6.245NDDSConﬁgVersion Class Reference . . . . . . . . . . . . . . . . 1557

6.246NDDSTransportSupport Class Reference . . . . . . . . . . . . . . 1559

6.247NDDSUtility Class Reference . . . . . . . . . . . . . . . . . . . . 1567

6.248TransportAllocationSettings t Struct Reference . . . . . . . . . . 1568

7 Example Documentation 1569

7.1 HelloWorld.cxx . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1569

7.2 HelloWorld.idl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1576

7.3 HelloWorld publisher.cxx . . . . . . . . . . . . . . . . . . . . . . 1577

7.4 HelloWorld subscriber.cxx . . . . . . . . . . . . . . . . . . . . . . 1582

7.5 HelloWorldPlugin.cxx . . . . . . . . . . . . . . . . . . . . . . . . 1588

7.6 HelloWorldSupport.cxx . . . . . . . . . . . . . . . . . . . . . . . 1609

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

Chapter 1

RTI Connext

Core Libraries and Utilities

Real-Time Innovations, Inc.

RTI Connext is network m iddleware for real-time distributed applications. It

provides the communications services that programmers need to distribute time-

critical data between embedded and/or enterprise devices or nodes. RTI Con-

next uses the publish-subscribe communications model to make data distribu-

tion eﬃcient and robust.

The RTI Connext Application Programming Interface (API) is based on the

OMG’s Data Distribution Service (DDS) speciﬁcation. The most recent publica-

tion of this speciﬁcation can be found in the Catalog of OMG Specifications

under ”Middleware Speciﬁcations”.

1.1 Feedback and Support for this Release.

For more information, visit our knowledge base (accessible from

https://support.rti.com/) to see sample code, general information on

RTI Connext, performance information, troubleshooting tips, and technical

details.

By its very nature, the knowledge base is continuously evolving and improv-

ing. We hope that you will ﬁnd it helpful. If there are questions that

you would like to see addressed or comments you would like to share, please

send e-mail to [email protected]. We can only guarantee a response for cus-

tomers with a current maintenance contract or subscription. To purchase a

maintenance contract or subscription, contact your local RTI representative

2 RTI Connext

(see http://www.rti.com/company/contact.html), send an email request to

[email protected], or call +1 (408) 990-7400.

Please do not hesitate to contact RTI with questions or comments about this

release. We welcome any input on how to improve RTI Connext to suit your

needs.

1.2 Available Documentation.

The documentation for this release is provided in two forms: the HTML API

reference documentation and PDF documents. If you are new to RTI Connext,

the Documentation Roadmap (p. 197) will provide direction on how to learn

about this product.

1.2.1 The PDF documents for the Core Libraries and Util-

ities are:

What’s New. An overview of the new features in this release.

Release Notes. System requirements, compatibility, what’s ﬁxed in this

release, and known issues.

Getting Started Guide. Download and installation instructions. It also

lays out the core value and concepts behind the product and takes you

step-by-step through the creation of a simple example application. Devel-

opers should read this document ﬁrst.

Getting Started Guide, Database Addendum. Additional installation

and s etup information for database usage.

Getting Started Guide, Embedded Systems Addendum. Additional in-

stallation and setup information for embedded systems.

User’s Manual. Introduction to RTI Connext, product tour and concep-

tual presentation of the functionality of RTI Connext.

Platform Notes. Speciﬁc details, such as compilation setting and li-

braries, related to building and using RTI Connext on the various sup-

ported platforms.

QoS Reference Guide. A compact summary of supported Quality of Ser-

vice (QoS) policies.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

1.2 Available Documentation. 3

XML-Based Application Creation Getting Started Guide. Details

on how to use XML-Based Application Creation, an experimental feature

in this release.

C API Reference Manual. A consolidated PDF version of the HTML C

API reference documentation.

C++ API Reference Manual. A consolidated PDF vers ion of the HTML

C++ API reference documentation.

Java API Reference Manual. A consolidate PDF version of the HTML

Java API reference documentation.

.NET API Reference Manual. A consolidated PDF version of the HTML

.Net API reference documentation.

1.2.2 The HTML API Reference documentation contains:

DDS API Reference (p. 203) - The DDS API reference.

RTI Connext API Reference (p. 216) - RTI Connext API’s indepen-

dent of the DDS standard.

Programming How-To’s (p. 217) - Describes and shows the common

tasks done using the API.

Programming Tools (p. 219) - RTI Connext helper tools.

The HTML API Reference documentation can be accessed through the tree view

in the left frame of the web browser window. The bulk of the documentation is

found under the entry labeled ”Modules”.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

4 RTI Connext

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

Chapter 2

Module Index

2.1 Modules

Here is a list of all modules:

Documentation Roadmap . . . . . . . . . . . . . . . . . . . . . . . . . 197

Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Using DDS:: Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . 201

DDS API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Domain Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

DomainParticipantFactory . . . . . . . . . . . . . . . . . . . . . 34

DomainParticipants . . . . . . . . . . . . . . . . . . . . . . . . 37

Built-in Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Participant Built-in Topics . . . . . . . . . . . . . . . . . . . 285

Topic Built-in Topics . . . . . . . . . . . . . . . . . . . . . . . 287

Publication Built-in Topics . . . . . . . . . . . . . . . . . . . 289

Subscription Built-in Topics . . . . . . . . . . . . . . . . . . . 291

Topic Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

User Data Type Support . . . . . . . . . . . . . . . . . . . . . 51

Type Code Support . . . . . . . . . . . . . . . . . . . . . . . . 56

Built-in Types . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

String Built-in Type . . . . . . . . . . . . . . . . . . . . . . . 293

KeyedString Built-in Type . . . . . . . . . . . . . . . . . . . 294

Octets Built-in Type . . . . . . . . . . . . . . . . . . . . . . . 295

KeyedOctets Built-in Type . . . . . . . . . . . . . . . . . . . 296

Dynamic Data . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

DDS-Sp e ciﬁc Primitive Types . . . . . . . . . . . . . . . . . . . 297

Publication Module . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Publishers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

6 Module Index

Data Writers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Flow Controllers . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Subscription Module . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Subscrib e rs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

DataReaders . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Read Conditions . . . . . . . . . . . . . . . . . . . . . . . . . 107

Query C onditions . . . . . . . . . . . . . . . . . . . . . . . . . 108

Data Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Sample States . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

View States . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Instance States . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Infrastructure Module . . . . . . . . . . . . . . . . . . . . . . . . . 118

Time Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

GUID Support . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

Sequence Number Support . . . . . . . . . . . . . . . . . . . . 310

Exception Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 312

Return C odes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

Status Kinds . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

QoS Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

USER DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

TOPIC DATA . . . . . . . . . . . . . . . . . . . . . . . . . . 346

GROUP DATA . . . . . . . . . . . . . . . . . . . . . . . . . . 347

DURABILITY . . . . . . . . . . . . . . . . . . . . . . . . . . 348

PRESENTATION . . . . . . . . . . . . . . . . . . . . . . . . 351

DEADLINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

LATENCY BUDGET . . . . . . . . . . . . . . . . . . . . . . 354

OWNERSHIP . . . . . . . . . . . . . . . . . . . . . . . . . . 355

OWNERSHIP STRENGTH . . . . . . . . . . . . . . . . . . . 357

LIVELINESS . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

TIME BASED FILTER . . . . . . . . . . . . . . . . . . . . . 360

PARTITION . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

RELIABILITY . . . . . . . . . . . . . . . . . . . . . . . . . . 362

DESTINATION ORDER . . . . . . . . . . . . . . . . . . . . 365

HISTORY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367

DURABILITY SERVICE . . . . . . . . . . . . . . . . . . . . 370

RESOURCE LIMITS . . . . . . . . . . . . . . . . . . . . . . 371

TRANSPORT PRIORITY . . . . . . . . . . . . . . . . . . . 373

LIFESPAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

WRITER DATA LIFECYCLE . . . . . . . . . . . . . . . . . 375

READER DATA LIFECYCLE . . . . . . . . . . . . . . . . . 376

ENTITY FACTORY . . . . . . . . . . . . . . . . . . . . . . . 377

Extended Qos Support . . . . . . . . . . . . . . . . . . . . . . 378

Thread Settings . . . . . . . . . . . . . . . . . . . . . . . 328

TRANSPORT SELECTION . . . . . . . . . . . . . . . . . . 382

TRANSPORT UNICAST . . . . . . . . . . . . . . . . . . . . 383

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

2.1 Modules 7

Unicast Settings . . . . . . . . . . . . . . . . . . . . . . . 379

TRANSPORT MULTICAST . . . . . . . . . . . . . . . . . . 384

Multicast Settings . . . . . . . . . . . . . . . . . . . . . . 380

Multicast Mapping . . . . . . . . . . . . . . . . . . . . . . 381

TRANSPORT MULTICAST MAPPING . . . . . . . . . . . 386

DISCOVERY . . . . . . . . . . . . . . . . . . . . . . . . . . . 387

NDDS DISCOVERY PEERS . . . . . . . . . . . . . . . . 388

TRANSPORT BUILTIN . . . . . . . . . . . . . . . . . . . . 396

WIRE PROTOCOL . . . . . . . . . . . . . . . . . . . . . . . 400

DATA READER RESOURCE LIMITS . . . . . . . . . . . . 407

DATA WRITER RESOURCE LIMITS . . . . . . . . . . . . 409

DATA READER PROTOCOL . . . . . . . . . . . . . . . . . 413

DATA WRITER PROTOCOL . . . . . . . . . . . . . . . . . 414

SYSTEM RESOURCE LIMITS . . . . . . . . . . . . . . . . 415

DOMAIN PARTICIPANT RESOURCE LIMITS . . . . . . . 416

EVENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417

DATABASE . . . . . . . . . . . . . . . . . . . . . . . . . . . 418

RECEIVER POOL . . . . . . . . . . . . . . . . . . . . . . . 419

PUBLISH MODE . . . . . . . . . . . . . . . . . . . . . . . . 420

DISCOVERY CONFIG . . . . . . . . . . . . . . . . . . . . . 423

ASYNCHRONOUS PUBLISHER . . . . . . . . . . . . . . . 428

TYPESUPPORT . . . . . . . . . . . . . . . . . . . . . . . . . 429

EXCLUSIVE AREA . . . . . . . . . . . . . . . . . . . . . . . 430

BATCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431

TYPE CONSISTENCY ENFORCEMENT . . . . . . . . . . 432

LOCATORFILTER . . . . . . . . . . . . . . . . . . . . . . . 434

MULTICHANNEL . . . . . . . . . . . . . . . . . . . . . . . . 435

PROPERTY . . . . . . . . . . . . . . . . . . . . . . . . . . . 436

AVAILABILITY . . . . . . . . . . . . . . . . . . . . . . . . . 442

ENTITY NAME . . . . . . . . . . . . . . . . . . . . . . . . . 445

PROFILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446

LOGGING . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450

Entity Support . . . . . . . . . . . . . . . . . . . . . . . . . . . 443

Conditions and WaitSets . . . . . . . . . . . . . . . . . . . . . 444

WriteParams . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447

Octet Buﬀer Support . . . . . . . . . . . . . . . . . . . . . . . . 451

Sequence Support . . . . . . . . . . . . . . . . . . . . . . . . . 455

Built-in Sequences . . . . . . . . . . . . . . . . . . . . . . . . 120

String Support . . . . . . . . . . . . . . . . . . . . . . . . . . . 456

Queries and Filters Syntax . . . . . . . . . . . . . . . . . . . . . . 208

RTI Connext API Reference . . . . . . . . . . . . . . . . . . . . . . . . 216

Clock Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Multi-channel DataWriters . . . . . . . . . . . . . . . . . . . . . . 122

Pluggable Transports . . . . . . . . . . . . . . . . . . . . . . . . . 124

Using Transport Plugins . . . . . . . . . . . . . . . . . . . . . . 130

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

8 Module Index

Built-in Transport Plugins . . . . . . . . . . . . . . . . . . . . . 136

Shared Memory Transp ort . . . . . . . . . . . . . . . . . . . . 257

UDPv4 Transport . . . . . . . . . . . . . . . . . . . . . . . . 265

UDPv6 Transport . . . . . . . . . . . . . . . . . . . . . . . . 275

Conﬁguration Utilities . . . . . . . . . . . . . . . . . . . . . . . . . 138

Unsupp orted Utilities . . . . . . . . . . . . . . . . . . . . . . . . . 143

Durability and Persistence . . . . . . . . . . . . . . . . . . . . . . . 144

System Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Conﬁguring QoS Proﬁles with XML . . . . . . . . . . . . . . . . . 151

Programming How-To’s . . . . . . . . . . . . . . . . . . . . . . . . . . 217

Publication Example . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Subscription Example . . . . . . . . . . . . . . . . . . . . . . . . . 155

Participant Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . 156

Topic Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

FlowController Us e Cases . . . . . . . . . . . . . . . . . . . . . . . 161

Publisher Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . 165

DataWriter Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . 166

Subscrib e r Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . 168

DataReader Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . 172

Entity Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Waitset Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

Transport Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Filter Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Creating Custom Content Filters . . . . . . . . . . . . . . . . . . . 191

Large Data Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . 195

Programming Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

rtiddsgen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

rtiddsping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

rtiddsspy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

Class Id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

Chapter 3

Class Index

3.1 Class Hierarchy

This inheritance list is sorted roughly, but not completely, alphabetically:

DDS AckResponseData t . . . . . . . . . . . . . . . . . . . . . . . . . 463

DDS AllocationSettings t . . . . . . . . . . . . . . . . . . . . . . . . . 464

DDS AsynchronousPublisherQosPolicy . . . . . . . . . . . . . . . . . . 466

DDS AvailabilityQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . 471

DDS BatchQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . 476

DDS BooleanSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480

DDS BuiltinTopicKey t . . . . . . . . . . . . . . . . . . . . . . . . . . 481

DDS BuiltinTopicReaderResourceLimits t . . . . . . . . . . . . . . . . 482

DDS ChannelSettings t . . . . . . . . . . . . . . . . . . . . . . . . . . 486

DDS ChannelSettingsSeq . . . . . . . . . . . . . . . . . . . . . . . . . 489

DDS CharSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490

DDS ContentFilterProperty t . . . . . . . . . . . . . . . . . . . . . . . 491

DDS Cookie t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493

DDS CookieSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494

DDS DatabaseQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . 495

DDS DataReaderCacheStatus . . . . . . . . . . . . . . . . . . . . . . . 500

DDS DataReaderProtocolQosPolicy . . . . . . . . . . . . . . . . . . . 501

DDS DataReaderProtocolStatus . . . . . . . . . . . . . . . . . . . . . 505

DDS DataReaderQos . . . . . . . . . . . . . . . . . . . . . . . . . . . 515

DDS DataReaderResourceLimitsQosPolicy . . . . . . . . . . . . . . . 521

DDS DataWriterCacheStatus . . . . . . . . . . . . . . . . . . . . . . . 534

DDS DataWriterProto c olQosPolicy . . . . . . . . . . . . . . . . . . . . 535

DDS DataWriterProto c olStatus . . . . . . . . . . . . . . . . . . . . . . 540

DDS DataWriterQos . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553

DDS DataWriterResourceLimitsQosPolicy . . . . . . . . . . . . . . . . 560

10 Class Index

DDS DeadlineQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . 567

DDS DestinationOrderQosPolicy . . . . . . . . . . . . . . . . . . . . . 570

DDS DiscoveryConﬁgQosPolicy . . . . . . . . . . . . . . . . . . . . . . 573

DDS DiscoveryQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . 582

DDS DomainParticipantFactoryQos . . . . . . . . . . . . . . . . . . . 586

DDS DomainParticipantQos . . . . . . . . . . . . . . . . . . . . . . . 588

DDS DomainParticipantResourceLimitsQosPolicy . . . . . . . . . . . 593

DDS DoubleSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613

DDS DurabilityQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . 614

DDS DurabilityServiceQosPolicy . . . . . . . . . . . . . . . . . . . . . 618

DDS Duration t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621

DDS DynamicData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622

DDS DynamicDataInfo . . . . . . . . . . . . . . . . . . . . . . . . . . 721

DDS DynamicDataMemberInfo . . . . . . . . . . . . . . . . . . . . . . 722

DDS DynamicDataProperty t . . . . . . . . . . . . . . . . . . . . . . . 725

DDS DynamicDataSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . 727

DDS DynamicDataTypeProperty t . . . . . . . . . . . . . . . . . . . . 728

DDS DynamicDataTypeSerializationProperty t . . . . . . . . . . . . . 729

DDS EndpointGroup t . . . . . . . . . . . . . . . . . . . . . . . . . . . 731

DDS EndpointGroupSeq . . . . . . . . . . . . . . . . . . . . . . . . . . 732

DDS EntityFactoryQosPolicy . . . . . . . . . . . . . . . . . . . . . . . 733

DDS EntityNameQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . 735

DDS EnumMember . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737

DDS EnumMemberSeq . . . . . . . . . . . . . . . . . . . . . . . . . . 738

DDS EventQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . 739

DDS ExclusiveAreaQosPolicy . . . . . . . . . . . . . . . . . . . . . . . 742

DDS ExpressionProperty . . . . . . . . . . . . . . . . . . . . . . . . . 745

DDS FactoryPluginSupport . . . . . . . . . . . . . . . . . . . . . . . . 746

DDS FilterSampleInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . 747

DDS FloatSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 748

DDS FlowControllerProperty t . . . . . . . . . . . . . . . . . . . . . . 749

DDS FlowControllerTokenBucketProperty t . . . . . . . . . . . . . . . 751

DDS GroupDataQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . 755

DDS GUID t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757

DDS HistoryQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . 758

DDS InconsistentTopicStatus . . . . . . . . . . . . . . . . . . . . . . . 762

DDS InstanceHandleSeq . . . . . . . . . . . . . . . . . . . . . . . . . . 764

DDS KeyedOctets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765

DDS KeyedOctetsSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . 767

DDS KeyedString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 768

DDS KeyedStringSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . 770

DDS LatencyBudgetQosPolicy . . . . . . . . . . . . . . . . . . . . . . 771

DDS LifespanQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . 773

DDS LivelinessChangedStatus . . . . . . . . . . . . . . . . . . . . . . 775

DDS LivelinessLostStatus . . . . . . . . . . . . . . . . . . . . . . . . . 777

DDS LivelinessQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . 779

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

3.1 Class Hierarchy 11

DDS Locator t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783

DDS LocatorFilter t . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785

DDS LocatorFilterQosPolicy . . . . . . . . . . . . . . . . . . . . . . . 787

DDS LocatorFilterSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . 789

DDS LocatorSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790

DDS LoggingQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . 791

DDS LongDoubleSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793

DDS LongLongSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 794

DDS LongSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 795

DDS MultiChannelQosPolicy . . . . . . . . . . . . . . . . . . . . . . . 796

DDS Octets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799

DDS OctetSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 801

DDS OctetsSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802

DDS OﬀeredDeadlineMissedStatus . . . . . . . . . . . . . . . . . . . . 803

DDS OﬀeredIncompatibleQosStatus . . . . . . . . . . . . . . . . . . . 805

DDS OwnershipQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . 807

DDS OwnershipStrengthQosPolicy . . . . . . . . . . . . . . . . . . . . 814

DDS ParticipantBuiltinTopicData . . . . . . . . . . . . . . . . . . . . 816

DDS ParticipantBuiltinTopicDataSeq . . . . . . . . . . . . . . . . . . 819

DDS PartitionQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . 820

DDS PresentationQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . 823

DDS ProductVersion t . . . . . . . . . . . . . . . . . . . . . . . . . . . 828

DDS ProﬁleQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . 830

DDS Property t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 833

DDS PropertyQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . 834

DDS PropertySeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837

DDS ProtocolVersion t . . . . . . . . . . . . . . . . . . . . . . . . . . 838

DDS PublicationBuiltinTopicData . . . . . . . . . . . . . . . . . . . . 839

DDS PublicationBuiltinTopicDataSeq . . . . . . . . . . . . . . . . . . 847

DDS PublicationMatchedStatus . . . . . . . . . . . . . . . . . . . . . 848

DDS PublisherQos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 851

DDS PublishModeQosPolicy . . . . . . . . . . . . . . . . . . . . . . . 853

DDS QosPolicyCount . . . . . . . . . . . . . . . . . . . . . . . . . . . 857

DDS QosPolicyCountSeq . . . . . . . . . . . . . . . . . . . . . . . . . 858

DDS ReaderDataLifecycleQosPolicy . . . . . . . . . . . . . . . . . . . 859

DDS ReceiverPoolQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . 862

DDS ReliabilityQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . 865

DDS ReliableReaderActivityChangedStatus . . . . . . . . . . . . . . . 869

DDS ReliableWriterCacheChangedStatus . . . . . . . . . . . . . . . . 871

DDS ReliableWriterCacheEventCount . . . . . . . . . . . . . . . . . . 874

DDS RequestedDeadlineMissedStatus . . . . . . . . . . . . . . . . . . 875

DDS RequestedIncompatibleQosStatus . . . . . . . . . . . . . . . . . . 877

DDS ResourceLimitsQosPolicy . . . . . . . . . . . . . . . . . . . . . . 879

DDS RtpsReliableReaderProtocol t . . . . . . . . . . . . . . . . . . . . 884

DDS RtpsReliableWriterProtocol t . . . . . . . . . . . . . . . . . . . . 889

DDS RtpsWellKnownPorts t . . . . . . . . . . . . . . . . . . . . . . . 905

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

12 Class Index

DDS SampleIdentity t . . . . . . . . . . . . . . . . . . . . . . . . . . . 911

DDS SampleInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 912

DDS SampleInfoSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922

DDS SampleLostStatus . . . . . . . . . . . . . . . . . . . . . . . . . . 923

DDS SampleRejectedStatus . . . . . . . . . . . . . . . . . . . . . . . . 925

DDS SequenceNumber t . . . . . . . . . . . . . . . . . . . . . . . . . . 927

DDS ShortSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 928

DDS StringSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929

DDS StructMember . . . . . . . . . . . . . . . . . . . . . . . . . . . . 931

DDS StructMemberSeq . . . . . . . . . . . . . . . . . . . . . . . . . . 933

DDS SubscriberQos . . . . . . . . . . . . . . . . . . . . . . . . . . . . 934

DDS SubscriptionBuiltinTopicData . . . . . . . . . . . . . . . . . . . . 936

DDS SubscriptionBuiltinTopicDataSeq . . . . . . . . . . . . . . . . . . 944

DDS SubscriptionMatchedStatus . . . . . . . . . . . . . . . . . . . . . 945

DDS SystemResourceLimitsQosPolicy . . . . . . . . . . . . . . . . . . 948

DDS ThreadSettings t . . . . . . . . . . . . . . . . . . . . . . . . . . . 950

DDS Time t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 953

DDS TimeBasedFilterQosPolicy . . . . . . . . . . . . . . . . . . . . . 954

DDS TopicBuiltinTopicData . . . . . . . . . . . . . . . . . . . . . . . 958

DDS TopicBuiltinTopicDataSeq . . . . . . . . . . . . . . . . . . . . . . 962

DDS TopicDataQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . 963

DDS TopicQos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 965

DDS TransportBuiltinQosPolicy . . . . . . . . . . . . . . . . . . . . . 969

DDS TransportMulticastMapping t . . . . . . . . . . . . . . . . . . . . 971

DDS TransportMulticastMappingFunction t . . . . . . . . . . . . . . . 973

DDS TransportMulticastMappingQosPolicy . . . . . . . . . . . . . . . 975

DDS TransportMulticastMappingSeq . . . . . . . . . . . . . . . . . . . 977

DDS TransportMulticastQosPolicy . . . . . . . . . . . . . . . . . . . . 978

DDS TransportMulticastSettings t . . . . . . . . . . . . . . . . . . . . 980

DDS TransportMulticastSettingsSeq . . . . . . . . . . . . . . . . . . . 982

DDS TransportPriorityQosPolicy . . . . . . . . . . . . . . . . . . . . . 983

DDS TransportSelectionQosPolicy . . . . . . . . . . . . . . . . . . . . 985

DDS TransportUnicastQosPolicy . . . . . . . . . . . . . . . . . . . . . 987

DDS TransportUnicastSettings t . . . . . . . . . . . . . . . . . . . . . 989

DDS TransportUnicastSettingsSeq . . . . . . . . . . . . . . . . . . . . 991

DDS TypeCode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 992

DDS TypeCodeFactory . . . . . . . . . . . . . . . . . . . . . . . . . . 1022

DDS TypeConsistencyEnforcementQosPolicy . . . . . . . . . . . . . . 1038

DDS TypeSupportQosPolicy . . . . . . . . . . . . . . . . . . . . . . . 1040

DDS UnionMember . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1042

DDS UnionMemberSeq . . . . . . . . . . . . . . . . . . . . . . . . . . 1044

DDS UnsignedLongLongSeq . . . . . . . . . . . . . . . . . . . . . . . . 1045

DDS UnsignedLongSeq . . . . . . . . . . . . . . . . . . . . . . . . . . 1046

DDS UnsignedShortSeq . . . . . . . . . . . . . . . . . . . . . . . . . . 1047

DDS UserDataQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . 1048

DDS ValueMember . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1050

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

3.1 Class Hierarchy 13

DDS ValueMemberSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . 1052

DDS VendorId t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1053

DDS VirtualSubscriptionBuiltinTopicData . . . . . . . . . . . . . . . . 1054

DDS VirtualSubscriptionBuiltinTopicDataSeq . . . . . . . . . . . . . . 1055

DDS WaitSetProp e rty t . . . . . . . . . . . . . . . . . . . . . . . . . . 1056

DDS WcharSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1058

DDS WireProtocolQosPolicy . . . . . . . . . . . . . . . . . . . . . . . 1059

DDS WriteParams t . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1067

DDS WriterDataLifecycleQosPolicy . . . . . . . . . . . . . . . . . . . 1071

DDS WstringSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1074

DDSCondition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1075

DDSGuardCondition . . . . . . . . . . . . . . . . . . . . . . . . . . 1263

DDSReadCondition . . . . . . . . . . . . . . . . . . . . . . . . . . 1374

DDSQueryCondition . . . . . . . . . . . . . . . . . . . . . . . . 1372

DDSStatusCondition . . . . . . . . . . . . . . . . . . . . . . . . . . 1376

DDSConditionSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1076

DDSConte ntFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1077

DDSWriterContentFilter . . . . . . . . . . . . . . . . . . . . . . . . 1441

DDSDataReaderSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1112

DDSDomainParticipantFactory . . . . . . . . . . . . . . . . . . . . . . 1216

DDSEntity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1253

DDSDomainEntity . . . . . . . . . . . . . . . . . . . . . . . . . . . 1138

DDSDataReader . . . . . . . . . . . . . . . . . . . . . . . . . . 1087

DDSDynamicDataReader . . . . . . . . . . . . . . . . . . . . 1245

DDSKeye dOctetsDataReader . . . . . . . . . . . . . . . . . . 1265

DDSKeye dStringDataReader . . . . . . . . . . . . . . . . . . 1293

DDSOctetsDataReader . . . . . . . . . . . . . . . . . . . . . 1326

DDSParticipantBuiltinTopicDataDataReader . . . . . . . . . 1341

DDSPublicationBuiltinTopicDataDataReader . . . . . . . . . 1344

DDSStringDataReader . . . . . . . . . . . . . . . . . . . . . . 1379

DDSSubscriptionBuiltinTopicDataDataReader . . . . . . . . 1417

DDSTopicBuiltinTopicDataDataReader . . . . . . . . . . . . 1425

FooDataReader . . . . . . . . . . . . . . . . . . . . . . . . . . 1444

DDSDataWriter . . . . . . . . . . . . . . . . . . . . . . . . . . 1113

DDSDynamicDataWriter . . . . . . . . . . . . . . . . . . . . 1252

DDSKeye dOctetsDataWriter . . . . . . . . . . . . . . . . . . 1276

DDSKeye dStringDataWriter . . . . . . . . . . . . . . . . . . 1304

DDSOctetsDataWriter . . . . . . . . . . . . . . . . . . . . . . 1331

DDSStringDataWriter . . . . . . . . . . . . . . . . . . . . . . 1383

FooDataWriter . . . . . . . . . . . . . . . . . . . . . . . . . . 1475

DDSPublisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1346

DDSSubscribe r . . . . . . . . . . . . . . . . . . . . . . . . . . . 1390

DDSTopic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1419

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

14 Class Index

DDSDomainParticipant . . . . . . . . . . . . . . . . . . . . . . . . 1139

DDSFlowController . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1259

DDSListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1318

DDSDataReaderListener . . . . . . . . . . . . . . . . . . . . . . . . 1108

DDSSubscribe rListener . . . . . . . . . . . . . . . . . . . . . . 1414

DDSDomainParticipantListener . . . . . . . . . . . . . . . . . 1243

DDSDataWriterListener . . . . . . . . . . . . . . . . . . . . . . . . 1133

DDSPublisherListener . . . . . . . . . . . . . . . . . . . . . . . 1370

DDSDomainParticipantListener . . . . . . . . . . . . . . . . . 1243

DDSTopicListener . . . . . . . . . . . . . . . . . . . . . . . . . . . 1430

DDSDomainParticipantListener . . . . . . . . . . . . . . . . . . 1243

DDSParticipantBuiltinTopicDataTypeSupport . . . . . . . . . . . . . 1342

DDSProp ertyQosPolicyHelper . . . . . . . . . . . . . . . . . . . . . . . 1343

DDSPublicationBuiltinTopicDataTypeSupport . . . . . . . . . . . . . 1345

DDSPublisherSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1371

DDSSubscribe rSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1416

DDSSubscriptionBuiltinTopicDataTypeSupport . . . . . . . . . . . . . 1418

DDSTopicBuiltinTopicDataTypeSupport . . . . . . . . . . . . . . . . 1426

DDSTopicDescription . . . . . . . . . . . . . . . . . . . . . . . . . . . 1427

DDSConte ntFilteredTopic . . . . . . . . . . . . . . . . . . . . . . . 1081

DDSMultiTopic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1322

DDSTopic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1419

DDSTypeSupport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1432

DDSDynamicDataTypeSupport . . . . . . . . . . . . . . . . . . . . 1246

DDSKeye dOctetsTypeSupport . . . . . . . . . . . . . . . . . . . . 1289

DDSKeye dStringTypeSupport . . . . . . . . . . . . . . . . . . . . 1314

DDSOctetsTypeSupport . . . . . . . . . . . . . . . . . . . . . . . . 1337

DDSStringTypeSupp ort . . . . . . . . . . . . . . . . . . . . . . . . 1386

FooTypeSupport . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1509

DDSWaitSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1433

Foo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1443

FooSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1494

NDDS Conﬁg LibraryVersion t . . . . . . . . . . . . . . . . . . . . . . 1518

NDDS Conﬁg LogMessage . . . . . . . . . . . . . . . . . . . . . . . . . 1520

NDDS Transport Address t . . . . . . . . . . . . . . . . . . . . . . . . 1521

NDDS Transport Property t . . . . . . . . . . . . . . . . . . . . . . . 1522

NDDS Transport Shmem Property t . . . . . . . . . . . . . . . . . . . 1530

NDDS Transport UDPv4 Property t . . . . . . . . . . . . . . . . . . . 1533

NDDS Transport UDPv6 Property t . . . . . . . . . . . . . . . . . . . 1542

NDDSConﬁgLogger . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1550

NDDSConﬁgLoggerDevice . . . . . . . . . . . . . . . . . . . . . . . . . 1555

NDDSConﬁgVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1557

NDDSTransportSupport . . . . . . . . . . . . . . . . . . . . . . . . . . 1559

NDDSUtility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1567

TransportAllocationSettings t . . . . . . . . . . . . . . . . . . . . . . . 1568

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

Chapter 4

Class Index

4.1 Class List

Here are the classes, structs, unions and interfaces with brief descriptions:

DDS AckResponseData t (Data payload of an application-level ac-

know ledgment ) . . . . . . . . . . . . . . . . . . . . . . . . . . 463

DDS AllocationSettings t (Resource allocation s ettings ) . . . . . 464

DDS AsynchronousPublisherQosPolicy (Conﬁgures the mecha-

nism that sends user data in an external middleware thread

) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466

DDS AvailabilityQosPolicy (Conﬁgures the availability of data ) . 471

DDS BatchQosPolicy (Used to conﬁgure batching of multiple sam-

ples into a single network packet in order to increase through-

put for small samples ) . . . . . . . . . . . . . . . . . . . . . . 476

DDS BooleanSeq (Instantiates FooSeq (p. 1494) < DDS Boolean

(p. 301) > ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480

DDS BuiltinTopi cKey t (The ke y type of the built-in topic types ) 481

DDS BuiltinTopi cReaderResourceLimits t (Built-in topic

reader’s resource limits ) . . . . . . . . . . . . . . . . . . . . . 482

DDS ChannelSettings t (Type used to conﬁgure the properties of

a channel ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486

DDS ChannelSettingsSeq (Declares IDL sequence< DDS -

ChannelSettings t (p. 486) > ) . . . . . . . . . . . . . . . . 489

DDS CharSeq (Instantiates FooSeq (p. 1494) < DDS Char

(p. 299) > ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490

DDS ContentFilterProperty t (<<eXtension>> ( p. 199) Type

used to provide all the required information to enable content

ﬁltering ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491

16 Class Index

DDS Cookie t (<<eXtension>> ( p. 199) Sequence of bytes iden-

tifying a written data sample, used when writing with param-

eters ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493

DDS CookieSeq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494

DDS DatabaseQosPolicy (Various threads and resource limits set-

tings used by RTI Connext to control its internal database

) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495

DDS DataReaderCacheStatus (<<eXtension>> ( p. 199) The

status of the reader’s cache ) . . . . . . . . . . . . . . . . . . 500

DDS DataReaderProtocolQosPolicy (Along with DDS -

WireProtocolQosPolicy (p. 1059) and DDS -

DataWriterProtocolQosPolicy (p. 535), this QoS policy

conﬁgures the DDS on-the-network protocol (RTPS) ) . . . . 501

DDS DataReaderProtocolStatus (<<eXtension>> ( p. 199)

The status of a reader’s internal protocol related metrics, like

the number of samples received, ﬁltered, rejected; and status

of wire protocol traﬃc ) . . . . . . . . . . . . . . . . . . . . . 505

DDS DataReaderQos (QoS policies supported by a DDS-

DataReader (p. 1087) entity ) . . . . . . . . . . . . . . . . . 515

DDS DataReaderResourceLimitsQosPolicy (Various settings

that conﬁgure how a DDSDataReader (p. 1087) allocates

and use s physical memory for internal resources ) . . . . . . . 521

DDS DataWriterCacheStatus (<<eXtension>> ( p. 199) The

status of the writer’s cache ) . . . . . . . . . . . . . . . . . . . 534

DDS DataWriterProtocolQosPolicy (Protocol that applies only

to DDSDataWriter (p. 1113) instances ) . . . . . . . . . . . 535

DDS DataWriterProtocolStatus (<<eXtension>> ( p. 199)

The status of a writer’s internal protocol related metrics, like

the number of samples pushed, pulled, ﬁltered; and status of

wire protocol traﬃc ) . . . . . . . . . . . . . . . . . . . . . . .

540

DDS DataWriterQos (QoS policies supported by a DDS-

DataWriter (p. 1113) entity ) . . . . . . . . . . . . . . . . . 553

DDS DataWriterResourceLimitsQosPolicy (Various settings

that conﬁgure how a DDSDataWriter (p. 1113) allocates

and use s physical memory for internal resources ) . . . . . . . 560

DDS DeadlineQosPolicy (Expresses the maximum duration (dead-

line) within which an instance is expected to be updated ) . . 567

DDS DestinationOrderQosPolicy (Controls how the middleware

will deal with data s ent by multiple DDSDataWriter

(p. 1113) entities for the same instance of data (i.e., same

DDSTopic (p. 1419) and key) ) . . . . . . . . . . . . . . . . 570

DDS DiscoveryConﬁgQosPolicy (Settings for discovery conﬁgura-

tion ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573

DDS DiscoveryQosPolicy (Conﬁgures the mechanism used by the

middleware to automatically discover and connect with new

remote applications ) . . . . . . . . . . . . . . . . . . . . . . . 582

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

4.1 Class List 17

DDS DomainParticipantFactoryQos (QoS policies supported by

a DDSDomainParticipantFactory (p. 1216) ) . . . . . . . 586

DDS DomainParticipantQos (QoS policies supported by a DDS-

DomainParticipant (p. 1139) entity ) . . . . . . . . . . . . 588

DDS DomainParticipantResourceLimitsQosPolicy (Various

settings that conﬁgure how a DDSDomainParticipant

(p. 1139) allocates and uses physical memory for internal

resources, including the maximum sizes of various properties ) 593

DDS DoubleSeq (Instantiates FooSeq (p. 1494) < DDS Double

(p. 300) > ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613

DDS DurabilityQosPolicy (This QoS p olicy sp ec iﬁes whether or

not RTI Connext will store and deliver previously published

data samples to new DDSDataReader (p. 1087) entities that

join the network later ) . . . . . . . . . . . . . . . . . . . . . 614

DDS DurabilityServiceQosPolicy (Various settings to conﬁgure

the external RTI Persistence Service used by RTI Connext

for DataWriters with a DDS DurabilityQosPol icy (p. 614)

setting of DDS PERSISTENT DURABILITY QOS

(p. 349) or DDS TRANSIENT DURABILITY QOS

(p. 349) ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 618

DDS Duration t (Type for duration representation ) . . . . . . . . . 621

DDS DynamicData (A sample of any complex data type, which can

be inspected and manipulated reﬂectively ) . . . . . . . . . . 622

DDS DynamicDataInfo (A descriptor for a DDS DynamicData

(p. 622) object ) . . . . . . . . . . . . . . . . . . . . . . . . . . 721

DDS DynamicDataMemberInfo (A descriptor for a single member

(i.e. ﬁeld) of dynamically deﬁned data type ) . . . . . . . . . 722

DDS DynamicDataProperty t (A collection of attributes used to

conﬁgure DDS DynamicData (p. 622) objects ) . . . . . . . 725

DDS DynamicDataSeq (An ordered collection of DDS -

DynamicData (p. 622) elements ) . . . . . . . . . . . . . . . 727

DDS DynamicDataTypeProperty t (A collection of attributes

used to conﬁgure DDSDynamicDataTypeSupport

(p. 1246) objects ) . . . . . . . . . . . . . . . . . . . . . . . . 728

DDS DynamicDataTypeSerializationProperty t (Prope rties

that govern how data of a certain type will be serialized on

the network ) . . . . . . . . . . . . . . . . . . . . . . . . . . . 729

DDS EndpointGroup t (Speciﬁes a group of endpoints that can be

collectively identiﬁed by a name and satisﬁed by a quorum ) . 731

DDS EndpointGroupSeq (A sequence of DDS -

EndpointGroup t (p. 731) ) . . . . . . . . . . . . . . . . . . 732

DDS EntityFactoryQosPolicy (A QoS policy for all DDSEntity

(p. 1253) types that can act as factories for one or more other

DDSEntity (p. 1253) types ) . . . . . . . . . . . . . . . . . . 733

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

18 Class Index

DDS EntityNameQosPolicy (Assigns a name and a role name

to a DDSDomainParticipant (p. 1139), DDSDataWriter

(p. 1113) or DDSDataReader (p. 1087). These names will

be visible during the discovery process and in RTI tools to

help you visualize and debug your system ) . . . . . . . . . . 735

DDS EnumMember (A description of a member of an enumeration ) 737

DDS EnumMemberSeq (Deﬁnes a sequence of enumerator mem-

bers ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738

DDS EventQosPolicy (Settings for event ) . . . . . . . . . . . . . . 739

DDS ExclusiveAreaQosPolicy (Conﬁgures multi-thread concur-

rency and deadlock prevention capabilities ) . . . . . . . . . . 742

DDS ExpressionProperty . . . . . . . . . . . . . . . . . . . . . . . 745

DDS FactoryPluginSupport (Interface for creating and manipulat-

ing DDS entities ) . . . . . . . . . . . . . . . . . . . . . . . . 746

DDS FilterSampleInfo . . . . . . . . . . . . . . . . . . . . . . . . . 747

DDS FloatSeq (Instantiates FooSeq (p. 1494) < DDS Float

(p. 300) > ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 748

DDS FlowControllerProperty t (Determines the ﬂow control

characteristics of the DDSFlowController (p. 1259) ) . . . 749

DDS FlowControllerTokenBucketProperty t

(DDSFlowController (p. 1259) uses the popular token

bucket approach for open loop network ﬂow control. The ﬂow

control characteristics are determined by the token bucket

prop e rties ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 751

DDS GroupDataQosPolicy (Attaches a buﬀer of opaque data that

is distributed by means of Built-i n Topics (p. 42) during

discovery ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755

DDS GUID t (Type for GUID (Global Unique Identiﬁer) represen-

tation ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757

DDS HistoryQosPolicy (Speciﬁes the behavior of RTI Connext in

the case where the value of a sample changes (one or more

times) before it can be successfully communicated to one or

more existing subscribers ) . . . . . . . . . . . . . . . . . . . . 758

DDS InconsistentTopicStatus (DDS INCONSISTENT -

TOPIC STATUS (p. 322) ) . . . . . . . . . . . . . . . . . . 762

DDS InstanceHandleSeq (Instantiates FooSeq (p. 1494) <

DDS InstanceHandle t (p. 53) > ) . . . . . . . . . . . . . . 764

DDS KeyedOctets (Built-in type consisting of a variable-length ar-

ray of opaque bytes and a string that is the key ) . . . . . . . 765

DDS KeyedOctetsSeq (Instantiates FooSeq (p. 1494) < DDS -

KeyedOctets (p. 765) > ) . . . . . . . . . . . . . . . . . . . 767

DDS KeyedString (Keyed string built-in type ) . . . . . . . . . . . 768

DDS KeyedStringSeq (Instantiates FooSeq (p. 1494) < DDS -

KeyedString (p. 768) > ) . . . . . . . . . . . . . . . . . . . . 770

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

4.1 Class List 19

DDS LatencyBudgetQosPolicy (Provides a hint as to the maxi-

mum acceptable delay from the time the data is written to

the time it is received by the subscribing applications ) . . . . 771

DDS LifespanQosPolicy (Speciﬁes how long the data written by the

DDSDataWriter (p. 1113) is considered valid ) . . . . . . . 773

DDS LivelinessChangedStatus (DDS LIVELINESS -

CHANGED STATUS (p. 325) ) . . . . . . . . . . . . . . . 775

DDS LivelinessLostStatus (DDS LIVELINESS LOST -

STATUS (p. 325) ) . . . . . . . . . . . . . . . . . . . . . . . 777

DDS LivelinessQosPolicy (Speciﬁes and conﬁgures the mechanism

that allows DDSDataReader (p. 1087) entities to detect

when DDSDataWriter (p. 1113) entities become discon-

nected or ”dead.” ) . . . . . . . . . . . . . . . . . . . . . . . . 779

DDS Locator t (<<eXtension>> ( p. 199) Type used to represent

the addressing information needed to send a message to an

RTPS Endpoint using one of the supported transports ) . . . 783

DDS LocatorFilter t (Speciﬁes the conﬁguration of an individual

channel within a MultiChannel DataWriter ) . . . . . . . . . 785

DDS LocatorFilterQosPolicy (The QoS policy used to report the

conﬁguration of a MultiChannel DataWriter as part of DDS -

PublicationBuiltinTopicData (p. 839) ) . . . . . . . . . . 787

DDS LocatorFilterSeq (Declares IDL sequence< DDS -

LocatorFilter t (p. 785) > ) . . . . . . . . . . . . . . . . . . 789

DDS LocatorSeq (Declares IDL sequence < DDS Locator t

(p. 783) > ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790

DDS LoggingQosPolicy (Conﬁgures the RTI Connext logging facil-

ity ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 791

DDS LongDoubleSeq (Instantiates FooSeq (p. 1494) < DDS -

LongDouble (p. 300) > ) . . . . . . . . . . . . . . . . . . . . 793

DDS LongLongSeq (Instantiates FooSeq (p. 1494) < DDS -

LongLong (p. 300) > ) . . . . . . . . . . . . . . . . . . . . . 794

DDS LongSeq (Instantiates FooSeq (p. 1494) < DDS Long

(p. 300) > ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 795

DDS MultiChannelQosPolicy (Conﬁgures the ability of a

DataWriter to send data on diﬀerent multicast groups (ad-

dresses) based on the value of the data ) . . . . . . . . . . . . 796

DDS Octets (Built-in type consisting of a variable-length array of

opaque bytes ) . . . . . . . . . . . . . . . . . . . . . . . . . . 799

DDS OctetSeq (Instantiates FooSeq (p. 1494) < DDS Octet

(p. 299) > ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 801

DDS OctetsSeq (Instantiates FooSeq (p. 1494) < DDS Octets

(p.

799) > ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802

DDS OﬀeredDeadlineMissedStatus (DDS OFFERED -

DEADLINE MISSED STATUS (p. 323) ) . . . . . . . . . 803

DDS OﬀeredIncompatibleQosStatus (DDS OFFERED -

INCOMPATIBLE QOS STATUS (p. 323) ) . . . . . . . . 805

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

20 Class Index

DDS OwnershipQosPolicy (Speciﬁes whether it is allowed for mul-

tiple DDSDataWriter (p. 1113) (s) to write the same in-

stance of the data and if so, how these modiﬁcations should

be arbitrated ) . . . . . . . . . . . . . . . . . . . . . . . . . . 807

DDS OwnershipStrengthQosPolicy (Speciﬁes the value of the

strength used to arbitrate among multiple DDSDataWriter

(p. 1113) objects that attempt to modify the same instance of

a data type (identiﬁed by DDSTopic (p. 1419) + key) ) . . . 814

DDS ParticipantBuiltinTopicData (Entry created when a Do-

mainParticipant object is discovered ) . . . . . . . . . . . . . 816

DDS ParticipantBuiltinTopicDataSeq (Instantiates FooSeq

(p. 1494) < DDS ParticipantBuiltinTopicData (p. 816)

> ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 819

DDS PartitionQosPolicy (Set of strings that introduces a logi-

cal partition among the topics visible by a DDSPublisher

(p. 1346) and a DDSSubscriber (p. 1390) ) . . . . . . . . . . 820

DDS PresentationQosPolicy (Speciﬁes how the samples represent-

ing changes to data instances are presented to a subscribing

application ) . . . . . . . . . . . . . . . . . . . . . . . . . . . 823

DDS ProductVersion t (<<eXtension>> ( p. 199) Type used to

represent the current version of RTI Connext ) . . . . . . . . 828

DDS ProﬁleQosPolicy (Conﬁgures the way that XML documents

containing QoS proﬁles are loaded by RTI Connext ) . . . . . 830

DDS Property t (Properties are name/value pairs objects ) . . . . . 833

DDS PropertyQosPoli cy (Stores name/value(string) pairs that can

be used to conﬁgure certain parameters of RTI Connext that

are not exposed through formal QoS policies. Can also be

used to store and propagate application-speciﬁc name/value

pairs that can be retrieved by user code during discovery ) . . 834

DDS PropertySeq (Declares IDL sequence < DDS Property t

(p. 833) > ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837

DDS ProtocolVersion t (<<eXtension>> ( p. 199) Type used to

represent the version of the RTPS protocol ) . . . . . . . . . 838

DDS PublicationBuiltinTopicData (Entry created when a DDS-

DataWriter (p. 1113) is discovered in association with its

Publisher ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 839

DDS PublicationBuiltinTopicDataSeq (Instantiates FooSeq

(p. 1494) < DDS PublicationBuiltinTopicData (p. 839)

> ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 847

DDS PublicationMatchedStatus (DDS PUBLICATION -

MATCHED STATUS (p. 325) ) . . . . . . . . . . . . . . . 848

DDS PublisherQos (QoS policies supported by a DDSPublisher

(p. 1346) entity ) . . . . . . . . . . . . . . . . . . . . . . . . . 851

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

4.1 Class List 21

DDS PublishModeQosPolicy (Speciﬁes how RTI Connext sends

application data on the network. This QoS policy can be

used to tell RTI Connext to use its own thread to send data,

instead of the user thread ) . . . . . . . . . . . . . . . . . . . 853

DDS QosPolicyCount (Type to hold a counter for a DDS -

QosPolicyId t (p. 341) ) . . . . . . . . . . . . . . . . . . . . 857

DDS QosPolicyCountSeq (Declares IDL sequence < DDS -

QosPolicyCount (p. 857) > ) . . . . . . . . . . . . . . . . . 858

DDS ReaderDataLifecycleQosPolicy (Controls how a

DataReader manages the lifecycle of the data that it

has received ) . . . . . . . . . . . . . . . . . . . . . . . . . . . 859

DDS ReceiverPoolQosPolicy (Conﬁgures threads used by RTI

Connext to receive and process data from transp orts (for ex-

ample, UDP sockets) ) . . . . . . . . . . . . . . . . . . . . . . 862

DDS ReliabilityQosPolicy (Indicates the level of reliability of-

fered/requested by RTI Connext ) . . . . . . . . . . . . . . . 865

DDS ReliableReaderActivityChangedStatus

(<<eXtension>> ( p. 199) Describes the activity (i.e.

are acknowledgements forthcoming) of reliable readers

matched to a reliable writer ) . . . . . . . . . . . . . . . . . . 869

DDS ReliableWriterCacheChangedStatus (<<eXtension>>

( p. 199) A summary of the state of a data writer’s cache of

unacknowle dged samples written ) . . . . . . . . . . . . . . . 871

DDS ReliableWriterCacheEventCount (<<eXtension>>

( p. 199) The number of times the number of unacknowl-

edged samples in the cache of a reliable writer hit a certain

well-deﬁned threshold ) . . . . . . . . . . . . . . . . . . . . . 874

DDS RequestedDeadlineMissedStatus (DDS -

REQUESTED DEADLINE MISSED STATUS

(p. 323) ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 875

DDS RequestedIncompatibleQosStatus (DDS -

REQUESTED INCOMPATIBLE QOS STATUS

(p. 323) ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 877

DDS ResourceLimitsQosPolicy (Controls the amount of physical

memory allocated for DDS entities, if dynamic allocations are

allowed, and how they occur. Also controls memory usage

among diﬀerent instance values for keyed topics ) . . . . . . . 879

DDS RtpsReliableReaderProtocol t (Qos related to reliable

reader protocol deﬁned in RTPS ) . . . . . . . . . . . . . . . 884

DDS RtpsReliableWriterProtocol t (QoS related to the reliable

writer protocol deﬁned in RTPS ) . . . . . . . . . . . . . . . . 889

DDS RtpsWellKnownPorts t (RTPS well-known port mapping

conﬁguration ) . . . . . . . . . . . . . . . . . . . . . . . . . . 905

DDS SampleIdentity t (Type deﬁnition for an Sample Identity ) . 911

DDS SampleInfo (Information that accompanies each sample that

is read or taken ) . . . . . . . . . . . . . . . . . . . . . . . . 912

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

22 Class Index

DDS SampleInfoSeq (Declares IDL sequence < DDS -

SampleInfo (p. 912) > ) . . . . . . . . . . . . . . . . . . . . 922

DDS SampleLostStatus (DDS SAMPLE LOST STATUS

(p. 324) ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 923

DDS SampleRejectedStatus (DDS SAMPLE R EJECTED -

STATUS (p. 324) ) . . . . . . . . . . . . . . . . . . . . . . . 925

DDS SequenceNumber t (Type for sequence number representa-

tion ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 927

DDS ShortSeq (Instantiates FooSeq (p. 1494) < DDS Short

(p. 299) > ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 928

DDS StringSeq (Instantiates FooSeq (p. 1494) < char∗ > with

value type semantics ) . . . . . . . . . . . . . . . . . . . . . . 929

DDS StructMember (A description of a member of a struct ) . . . 931

DDS StructMemberSeq (Deﬁnes a sequence of struct members ) . 933

DDS SubscriberQos (QoS policies supported by a DDSSubscriber

(p. 1390) entity ) . . . . . . . . . . . . . . . . . . . . . . . . . 934

DDS SubscriptionBuiltinTopicDat a (Entry created when a

DDSDataReader (p. 1087) is discovered in association with

its Subscriber ) . . . . . . . . . . . . . . . . . . . . . . . . . . 936

DDS SubscriptionBuiltinTopicDat aSeq (Instantiates FooSeq

(p. 1494) < DDS SubscriptionBuilt inTopicData (p. 936)

> ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 944

DDS SubscriptionMatchedStatus (DDS SUBSCRIPTION -

MATCHED STATUS (p. 326) ) . . . . . . . . . . . . . . . 945

DDS SystemResourceLimitsQosPolicy (Conﬁgures DDSDo-

mainParticipant (p. 1139)-independent resources used by

RTI Connext. Mainly used to change the maximum num-

ber of DDSDomainParticipant (p. 1139) entities that can

be created within a single process (address space) ) . . . . . . 948

DDS ThreadSettings t (The properties of a thread of execution ) . 950

DDS Time t (Type for time representation ) . . . . . . . . . . . . . 953

DDS TimeBasedFilterQosPolicy (Filter that allows a DDS-

DataReader (p. 1087) to specify that it is interes ted only

in (potentially) a subset of the values of the data ) . . . . . . 954

DDS TopicBuilti nTopicData (Entry created when a Topic object

discovered ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 958

DDS TopicBuilti nTopicDataSeq (Instantiates FooSeq (p. 1494)

< DDS TopicBuiltinTopicData (p. 958) > ) . . . . . . . . 962

DDS TopicDataQosPolicy (Attaches a buﬀer of opaque data that

is distributed by means of Built-i n Topics (p. 42) during

discovery ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 963

DDS TopicQos (QoS policies supported by a DDSTopic (p. 1419)

entity ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 965

DDS TransportBuiltinQosPolicy (Speciﬁes which built-in trans-

ports are used ) . . . . . . . . . . . . . . . . . . . . . . . . . . 969

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

4.1 Class List 23

DDS TransportMulticastMapping t (Type representing a list of

multicast mapping elements ) . . . . . . . . . . . . . . . . . . 971

DDS TransportMulticastMappingFunction t (Type represent-

ing an external mapping function ) . . . . . . . . . . . . . . . 973

DDS TransportMulticastMappingQosPol icy (Speciﬁes a list of

topic expressions and multicast addresses that can be used by

an Entity with a speciﬁc topic name to receive data ) . . . . . 975

DDS TransportMulticastMappingSeq (Declares IDL sequence<

DDS TransportMulticastMapping t (p. 971) > ) . . . . . 977

DDS TransportMulticastQosPolicy (Speciﬁes the multicast ad-

dress on which a DDSDataReader (p. 1087) wants to receive

its data. It can also specify a port number as well as a subset

of the available (at the DDSDomainParti cipant (p. 1139)

level) transports with which to receive the multicast data ) . 978

DDS TransportMulticastSettings t (Type representing a list of

multicast locators ) . . . . . . . . . . . . . . . . . . . . . . . . 980

DDS TransportMulticastSettingsSeq (Declares IDL sequence<

DDS TransportMulticastSettings t (p. 980) > ) . . . . . 982

DDS TransportPriorityQosPolicy (This QoS policy allows the ap-

plication to take advantage of transports that are capable of

sending messages with diﬀerent priorities ) . . . . . . . . . . . 983

DDS TransportSelectionQosPolicy (Speciﬁes the physical trans-

ports a DDSDataWriter (p. 1113) or DDSDataReader

(p. 1087) may use to send or receive data ) . . . . . . . . . . . 985

DDS TransportUnicastQosPol icy (Speciﬁes a subset of transports

and a port number that can be used by an Entity to receive

data ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987

DDS TransportUnicastSettings t (Type representing a list of uni-

cast locators ) . . . . . . . . . . . . . . . . . . . . . . . . . . . 989

DDS TransportUnicastSettingsSeq (Declares IDL sequence<

DDS TransportUnicastSettings t (p. 989) > ) . . . . . . 991

DDS TypeCode (The deﬁnition of a particular data type, which you

can use to inspect the name, members, and other properties

of types generated with rtiddsgen (p. 220) or to modify types

you deﬁne yourself at runtime ) . . . . . . . . . . . . . . . . . 992

DDS TypeCodeFactory (A singleton factory for creating, copying,

and dele ting data type deﬁnitions dynamically ) . . . . . . . 1022

DDS TypeConsistencyEnforcementQosPolicy (Deﬁnes the rules

for determining whether the type used to publish a given topic

is consistent with that used to subscribe to it ) . . . . . . . . 1038

DDS TypeSupportQosPolicy (Allows you to attach application-

speciﬁc values to a DataWriter or DataReader that are passed

to the serialization or deserialization routine of the associated

data type ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1040

DDS UnionMember (A description of a member of a union ) . . . . 1042

DDS UnionMemberSeq (Deﬁnes a sequence of union members ) . 1044

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

24 Class Index

DDS UnsignedLongLongSeq (Instantiates FooSeq (p. 1494) <

DDS UnsignedLongLong (p. 300) > ) . . . . . . . . . . . . 1045

DDS UnsignedLongSeq (Instantiates FooSeq (p. 1494) < DDS -

UnsignedLong (p. 300) > ) . . . . . . . . . . . . . . . . . . 1046

DDS UnsignedShortSeq (Instantiates FooSeq (p. 1494) < DDS -

UnsignedShort (p. 299) > ) . . . . . . . . . . . . . . . . . . 1047

DDS UserDataQosPolicy (Attaches a buﬀer of opaque data that

is distributed by means of Built-i n Topics (p. 42) during

discovery ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1048

DDS ValueMember (A description of a member of a value type ) . 1050

DDS ValueMemberSeq (Deﬁnes a sequence of value members ) . . 1052

DDS VendorId t (<<eXtension>> ( p. 199) Type used to repre-

sent the vendor of the s ervice implementing the RTPS protocol )1053

DDS VirtualSubscriptionBuiltinTopicData . . . . . . . . . . . . 1054

DDS VirtualSubscriptionBuiltinTopicDataSeq . . . . . . . . . 1055

DDS WaitSetProperty t (<<eXtension>> ( p. 199) Speciﬁes the

DDSWaitSet (p. 1433) behavior for multiple trigger events ) 1056

DDS WcharSeq (Instantiates FooSeq (p. 1494) < DDS Wchar

(p. 299) > ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1058

DDS WireProtocolQosPolicy (Speciﬁes the wire-protocol-related

attributes for the DDSDomainParticipant (p. 1139) ) . . . 1059

DDS WriteParams t (<<eXtension>> ( p. 199) Input pa-

rameters for writing with FooDataWriter::write w -

params (p. 1487), FooDataWriter::dispose w params

(p. 1491), FooDataWriter::register instance w params

(p. 1480), FooDataWriter::unregister instance w -

params (p. 1483) ) . . . . . . . . . . . . . . . . . . . . . . . . 1067

DDS WriterDataLifecycleQosPolicy (Controls how a DDS-

DataWriter (p. 1113) handles the lifecycle of the instances

(keys) that it is registered to manage ) . . . . . . . . . . . . . 1071

DDS WstringSeq (Instantiates FooSeq (p. 1494) < DDS Wchar

(p. 299)∗ > ) . . . . . . . . . . . . . . . . . . . . . . . . . . . 1074

DDSCondition (<<interface>> ( p. 199) Root class for all the con-

ditions that may be attached to a DDSWaitSet (p. 1433) ) . 1075

DDSConditionSeq (Instantiates FooSeq (p. 1494) < DDSCondi-

tion (p. 1075) > ) . . . . . . . . . . . . . . . . . . . . . . . . 1076

DDSContentFilter (<<interface>> ( p. 199) Interface to be used

by a custom ﬁlter of a DDSContentFilteredTopic (p. 1081) )1077

DDSContentFilteredTopic (<<interface>> ( p. 199) Specializa-

tion of DDSTopicDescription (p. 1427) that allows for

content-based subscriptions ) . . . . . . . . . . . . . . . . . . 1081

DDSDataReader (<<interface>> ( p. 199) Allows the application

to: (1) declare the data it wishes to receive (i.e. make a

subscription) and (2) access the data received by the attached

DDSSubscriber (p. 1390) ) . . . . . . . . . . . . . . . . . . 1087

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

4.1 Class List 25

DDSDataReaderListener (<<interface>> ( p. 199) DDSLis-

tener (p. 1318) for reader status ) . . . . . . . . . . . . . . . 1108

DDSDataReaderSeq (Declares IDL sequence < DDS-

DataReader (p. 1087) > ) . . . . . . . . . . . . . . . . . . . 1112

DDSDataWriter (<<interface>> ( p. 199) Allows an application

to set the value of the data to be published under a given

DDSTopic (p. 1419) ) . . . . . . . . . . . . . . . . . . . . . . 1113

DDSDataWriterListener (<<interface>> ( p. 199) DDSLis-

tener (p. 1318) for writer status ) . . . . . . . . . . . . . . . 1133

DDSDomainEntity (<<interface>> ( p. 199) Abstract base class

for all DDS entities except for the DDSDomainParticipant

(p. 1139) ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1138

DDSDomainParticipant (<<interface>> ( p. 199 ) Container for

all DDSDomainEntity (p. 1138) objects ) . . . . . . . . . . 1139

DDSDomainParticipantFactory (<<singleton>> ( p. 200)

<<interface>> ( p. 199) Allows creation and destruction of

DDSDomainParticipant (p. 1139) objects ) . . . . . . . . . 1216

DDSDomainParticipantListener (<<interface>> ( p. 199) Lis-

tener for participant status ) . . . . . . . . . . . . . . . . . . 1243

DDSDynamicDataReader (Reads (subscribes to) objects of type

DDS DynamicData (p. 622) ) . . . . . . . . . . . . . . . . . 1245

DDSDynamicDataTypeSupport (A factory for registering a dy-

namically deﬁned type and creating DDS DynamicData

(p. 622) objects ) . . . . . . . . . . . . . . . . . . . . . . . . . 1246

DDSDynamicDataWriter (Writes (publishes) objects of type

DDS DynamicData (p. 622) ) . . . . . . . . . . . . . . . . . 1252

DDSEntity (<<interface>> ( p. 199) Abstract base class for all the

DDS objects that support QoS policies, a listener, and a status

condition ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1253

DDSFlowController (<<interface>> ( p. 199) A ﬂow controller

is the object responsible for shaping the network traﬃc by

determining when attached asynchronous DDSDataWriter

(p. 1113) instances are allowed to write data ) . . . . . . . . . 1259

DDSGuardCondition (<<interface>> ( p. 199) A speciﬁc

DDSCondition (p. 1075) whose trigger value is com-

pletely under the control of the application ) . . . . . . . . . 1263

DDSKeyedOctetsDataReader (<<interface>> ( p. 199) Instan-

tiates DataReader < DDS KeyedOctets (p. 765) > ) . . . . 1265

DDSKeyedOctetsDataWriter (<<interface>> ( p. 199) Instan-

tiates DataWriter < DDS KeyedOctets (p. 765) > ) . . . . 1276

DDSKeyedOctetsTypeSupport (<<interface>> ( p. 199)

DDS

KeyedOctets (p. 765) type support ) . . . . . . . . . . 1289

DDSKeyedStringDataReader (<<interface>> ( p. 199) Instan-

tiates DataReader < DDS KeyedString (p. 768) > ) . . . . 1293

DDSKeyedStringDataWriter (<<interface>> ( p. 199) Instanti-

ates DataWriter < DDS KeyedString (p. 768) > ) . . . . . 1304

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

26 Class Index

DDSKeyedStringTypeSupport (<<interface>> ( p. 199) Keyed

string type support ) . . . . . . . . . . . . . . . . . . . . . . . 1314

DDSListener (<<interface>> ( p. 199) Abstract base class for all

Listener interfaces ) . . . . . . . . . . . . . . . . . . . . . . . 1318

DDSMultiTopic ([Not supported (optional)] <<interface>>

( p. 199) A specialization of DDSTopicDescrip-

tion (p. 1427) that allows subscriptions that com-

bine/ﬁlter/rearrange data coming from several topics

) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1322

DDSOctetsDataReader (<<interface>> ( p. 199) Instantiates

DataReader < DDS Octets (p. 799) > ) . . . . . . . . . . . 1326

DDSOctetsDataWriter (<<interface>> ( p. 199) Instantiates

DataWriter < DDS Octets (p. 799) > ) . . . . . . . . . . . 1331

DDSOctetsTypeSupport (<<interface>> ( p. 199) DDS -

Octets (p. 799) type support ) . . . . . . . . . . . . . . . . . 1337

DDSParticipantBuiltinTopicDataDataReader (Instantiates

DataReader < DDS ParticipantBuiltinTopicData

(p. 816) > ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1341

DDSParticipantBuiltinTopicDataTypeSupport (Instantiates

TypeSupport < DDS ParticipantBuiltinTopicData

(p. 816) > ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1342

DDSPropertyQosPolicyHelper (Policy Helpers which facilitate

management of the properties in the input policy ) . . . . . . 1343

DDSPublicationBuiltinTopicDataDataReader (Instantiates

DataReader < DDS PublicationBuiltinTopicData

(p. 839) > ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1344

DDSPublicationBuiltinTopicDataTypeSupport (Instantiates

TypeSupport < DDS Publi cationBui lti nTopicData

(p. 839) > ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1345

DDSPublisher (<<interface>> ( p. 199) A publisher is the object

responsible for the actual dissemination of publications ) . . . 1346

DDSPublisherListener (<<interface>> ( p. 199) DDSListener

(p. 1318) for DDSPublisher (p. 1346) status ) . . . . . . . . 1370

DDSPublisherSeq (Declares IDL sequence < DDSPublisher

(p. 1346) > ) . . . . . . . . . . . . . . . . . . . . . . . . . . . 1371

DDSQueryCondition (<<interface>> ( p. 199) These are spe-

cialised DDSReadCondition (p. 1374) objects that allow

the application to also specify a ﬁlter on the locally available

data ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1372

DDSReadCondition (<<interface>> ( p. 199) Conditions speciﬁ-

cally dedicated to read operations and attached to one DDS-

DataReader (p. 1087) ) . . . . . . . . . . . . . . . . . . . . . 1374

DDSStatusCondition (<<interface>> ( p. 199) A speciﬁc

DDSCondition (p. 1075) that is associated with each

DDSEntity (p. 1253) ) . . . . . . . . . . . . . . . . . . . . . 1376

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

4.1 Class List 27

DDSStringDataReader (<<interface>> ( p. 199) Instantiates

DataReader < char∗ > ) . . . . . . . . . . . . . . . . . . . . . 1379

DDSStringDataWriter (<<interface>> ( p. 199) Instantiates

DataWriter < char∗ > ) . . . . . . . . . . . . . . . . . . . . . 1383

DDSStringTypeSupport (<<interface>> ( p. 199) String type

support ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1386

DDSSubscriber (<<interface>> ( p. 199) A subscriber is the ob-

ject responsible for actually receiving data from a subscription

) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1390

DDSSubscriberListener (<<interface>> ( p. 199) DDSListener

(p. 1318) for status about a subscriber ) . . . . . . . . . . . . 1414

DDSSubscriberSeq (Declares IDL sequence < DDSSubscriber

(p. 1390) > ) . . . . . . . . . . . . . . . . . . . . . . . . . . . 1416

DDSSubscriptionBuiltinTopicDataDataReader (Instantiates

DataReader < DDS SubscriptionBuilt inTopicData

(p. 936) > ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1417

DDSSubscriptionBuiltinTopicDataTypeSupport (Instantiates

TypeSupport < DDS SubscriptionBuiltinTopicData

(p. 936) > ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1418

DDSTopic (<<interface>> ( p. 199) The most basic description of

the data to be published and subscribed ) . . . . . . . . . . . 1419

DDSTopicBuiltinTopicDataDataReader (Instantiates

DataReader < DDS TopicBuiltinTopicData (p. 958)

> ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1425

DDSTopicBuiltinTopicDataTypeSupport (Instantiates

TypeSupport < DDS TopicBuiltinTopicData (p. 958) > ) 1426

DDSTopicDescription (<<interface>> ( p. 199) Base class

for DDSTopic (p. 1419), DDSContentFilteredTopic

(p. 1081), and DDSMultiTopic (p. 1322) ) . . . . . . . . . . 1427

DDSTopicListener (<<interface>> ( p. 199) DDSListener

(p. 1318) for DDSTopic (p. 1419) entities ) . . . . . . . . . . 1430

DDSTypeSupport (<<interface>> ( p. 199) An abstract marker

inte rface that has to be specialized for each concrete user data

type that will be used by the application ) . . . . . . . . . . . 1432

DDSWaitSet (<<interface>> ( p. 199) Allows an application

to wait until one or more of the attached DDSCon-

dition (p. 1075) objects has a trigger value of DDS -

BOOLEAN TRUE (p. 298) or else until the timeout expires

) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1433

DDSWriterContentFilter . . . . . . . . . . . . . . . . . . . . . . . 1441

Foo (A representative user-deﬁned data type ) . . . . . . . . . . . . . 1443

FooDataReader (<<interface>> ( p. 199) <<generic>>

( p. 199) User data type-speciﬁc data reader ) . . . . . . . . . 1444

FooDataWriter (<<interface>> ( p. 199) <<generic>> ( p. 199)

User data type speciﬁc data writer ) . . . . . . . . . . . . . . 1475

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

28 Class Index

FooSeq (<<interface>> ( p. 199) <<generic>> ( p. 199) A type-

safe, ordered collection of elements. The type of these ele-

ments is referred to in this documentation as Foo (p. 1443)

) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1494

FooTypeSupport (<<interface>> ( p. 199) <<generic>>

( p. 199) User data type speciﬁc interface ) . . . . . . . . . . . 1509

NDDS Conﬁg LibraryVersion t (The version of a single library

shipped as part of an RTI Connext distribution ) . . . . . . . 1518

NDDS Conﬁg LogMessage (Log message ) . . . . . . . . . . . . . 1520

NDDS Transport Address t (Addresses are stored individually as

network-ordered bytes ) . . . . . . . . . . . . . . . . . . . . . 1521

NDDS Transport Property t (Base structure that must be inher-

ited by derived Transport Plugin classes ) . . . . . . . . . . . 1522

NDDS Transport Shmem Property t (Subclass of NDDS -

Transport Property t (p. 1522) allowing speciﬁcation of

parameters that are speciﬁc to the shared-memory transport ) 1530

NDDS Transport UDPv4 Property t (Conﬁgurable IPv4/UDP

Transport-Plugin properties ) . . . . . . . . . . . . . . . . . . 1533

NDDS Transport UDPv6 Property t (Conﬁgurable IPv6/UDP

Transport-Plugin properties ) . . . . . . . . . . . . . . . . . . 1542

NDDSConﬁgLogger (<<interface>> ( p. 199) The singleton type

used to conﬁgure RTI Connext logging ) . . . . . . . . . . . . 1550

NDDSConﬁgLoggerDevice (<<interface>> ( p. 199) Logging

device interface. Use for user-deﬁned logging devices ) . . . . 1555

NDDSConﬁgVersion (<<interface>> ( p. 199) The version of an

RTI Connext distribution ) . . . . . . . . . . . . . . . . . . . 1557

NDDSTransportSupport (<<interface>> ( p. 199) The utility

class used to conﬁgure RTI Connext pluggable transports ) . 1559

NDDSUtility (Unsupported utility APIs ) . . . . . . . . . . . . . . . 1567

TransportAllocationSettings t (Allo c ation settings used by various

internal buﬀers ) . . . . . . . . . . . . . . . . . . . . . . . . . 1568

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

Chapter 5

Module Documentation

5.1 Clock Selection

APIs related to clock selection. RTI Connext uses clocks to measure time and

generate timestamps.

The middleware uses two clocks, an internal clock and an external clock. The

internal clock is used to measure time and handles all timing in the middleware.

The external clock is used solely to generate timestamps, such as the source

timestamp and the reception timestamp, in addition to providing the time given

by DDSDomainParticipant::get current time (p. 1191).

5.1.1 Available Clocks

Two clock implementations are generally available, the monotonic clock and the

realtime clock.

The monotonic clock provides times that are monotonic from a clock that is not

adjustable. This clock is useful to use in order to not be subject to changes in

the system or realtime clock, which may be adjusted by the user or via time

synchronization protocols. However, this time generally starts from an arbitrary

point in time, such as system startup. Note that this clock is not available for

all architectures. Please see the Platform Notes for the architectures on which

it is supported. For the purposes of clock selection, this clock can be referenced

by the name ”monotonic”.

The realtime clock provides the realtime of the system. This clo ck may generally

be monotonic but may not be guaranteed to be so. It is adjustable and may b e

subject to small and large changes in time. The time obtained from this clock

is generally a meaningful time in that it is the amount of time from a known

30 Module Documentation

epoch. For the purposes of clock selection, this clock can be referenced by the

names ”realtime” or ”system”.

5.1.2 Clock Selection Strategy

By default, both the internal and external clocks use the real-time clock. If you

want your application to be robust to changes in the system time, you may use

the monotonic clock as the internal clock, and leave the system clock as the

external clock. Note, however, that this may slightly diminish performance in

that both the send and receive paths may need to obtain times from both clocks.

Since the monotonic clock is not available on all architectures, you may want

to specify ”monotonic,realtime” for the internal clock (see the table below). By

doing so, the middleware will attempt to use the monotonic clock if available,

and w ill fall back to the realtime clock if the monotonic clock is not available.

If you want your application to be robust to changes in the system time, you

are not relying on source timestamps, and you want to avoid obtaining times

from both clocks, you may use the monotonic clock for both the internal and

external clocks.

5.1.3 Conﬁguring Clock Selection

To conﬁgure the clock selection, use the PROPERTY (p. 436) QoS policy

associated with the DDSDomainParticipant (p. 1139).

See also:

DDS PropertyQosPoli cy (p. 834)

The following table lists the supported clock selection properties.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.1 Clock Selection 31

Property Description

dds.clock.external clock Comma-delimited list of clocks to

use for the external clock, in the

order of preference. Valid clock

names are ”realtime”, ”system”,

and ”m onotonic”.

Default: ”realtime”

dds.clock.internal clock Comma-delimited list of clocks to

use for the internal clock, in the

order of preference. Valid clock

names are ”realtime”, ”system”,

and ”m onotonic”.

Default: ”realtime”

Table 5.1: Clock Selection Properties

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

32 Module Documentation

5.2 Domain Module

Contains the DDSDomainParticipant (p. 1139) class that acts as an entry-

point of RTI Connext and acts as a factory for many of the classes. The DDS-

DomainParticipant (p. 1139) also acts as a container for the other objects

that make up RTI Connext.

Modules

DomainParticipantFactory

DDSDomainParticipantFactory ( p. 1216) entity and associated elements

DomainParticipants

DDSDomainParticipant ( p. 1139) en tity and associated elements

Built-in Topics

Built-in objects created by RTI Connext but accessible to the application.

Deﬁnes

#deﬁne DDSTheParticipantFactory DDSDomainParticipantFac-

tory::get instance()

Can be used as an alias for the singleton factory returned by the operation

DDSDomainParticipantFactory::get instance() ( p. 1221).

Typedefs

typedef DDS DOMAINID TYPE NATIVE DDS DomainId t

An integer that indicates in which domain a DDSDomainParticipant

( p. 1139) communicates.

5.2.1 Detailed Description

Contains the DDSDomainParticipant (p. 1139) class that acts as an entry-

point of RTI Connext and acts as a factory for many of the classes. The DDS-

DomainParticipant (p. 1139) also acts as a container for the other objects

that make up RTI Connext.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.2 Domain Module 33

5.2.2 Deﬁne Documentation

5.2.2.1 #deﬁne DDSTheParticipantFactory DDSDomainPartici-

pantFactory::get instance()

Can be used as an alias for the singleton factory returned by the operation

DDSDomainParticipantFactory::get instance() (p. 1221).

See also:

DDSDomainParticipantFactory::get instance (p. 1221)

Examples:

HelloWorld publisher.cxx, and HelloWorld subscriber.cxx.

5.2.3 Typedef Documentation

5.2.3.1 typedef DDS DOMAINID TYPE NATIVE

DDS DomainId t

An integer that indicates in which domain a DDSDomainParticipant

(p. 1139) communicates.

Participants with the same DDS DomainId t (p. 33) are said to be in the

same domain, and can thus communicate with one another.

The lower limit for a domain ID is 0. The upper limit for a domain ID is de-

termined by the guidelines stated in DDS RtpsWellKnownPorts t (p. 905)

(speciﬁcally DDS RtpsWellKnownPorts t::domain id gain (p. 907))

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

34 Module Documentation

5.3 DomainParticipantFactory

DDSDomainParticipantFactory (p. 1216) entity and associated elements

Classes

class DDSDomainParticipantFactory

<<singleton>> (p. 200) <<interface>> (p. 199) Allows creation and de-

struction of DDSDomainParticipant ( p. 1139) objects.

struct DDS DomainParticipantFactoryQos

QoS policies supported by a DDSDomainParticipantFactory ( p. 1216).

Typedefs

typedef DDS ReturnCode t(∗ DDSDomainParti cipantFactory -

RegisterTypeFunction )(DDSDomainParticipant ∗participant,

const char ∗type name)

Prototype of a register type function.

Variables

struct DDS DomainParticipantQos DDS PARTICIPANT QOS -

DEFAULT

Special value for creating a DomainParticipant with default QoS.

5.3.1 Detailed Description

DDSDomainParticipantFactory (p. 1216) entity and associated elements

5.3.2 Typedef Documentation

5.3.2.1 typedef DDS ReturnCode t(∗ DDSDomainParticipant-

Factory RegisterTypeFunction)(DDSDomainParticipant

∗participant, const char ∗type name)

Prototype of a register type function.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.3 DomainParticipantFactory 35

Parameters:

participant <<inout>> ( p. 200) DDSDomainParticipant (p. 1139)

participant the type is registered with.

type name <<in>> ( p. 200) Name the type is registered with.

Returns:

One of the Standard Return Codes (p. 314)

5.3.3 Variable Documentation

5.3.3.1 struct DDS DomainParticipantQos

DDS PARTICIPANT QOS DEFAULT

Special value for creating a DomainParticipant with default QoS.

When used in DDSDomainParticipantFactory::create participant

(p. 1233), this special value is used to indicate that the DDSDomainPartici-

pant (p. 1139) should be created with the default DDSDomainParticipant

(p. 1139) QoS by means of the operation DDSDomainParticipantFac-

tory::get default participant qos() (p. 1224) and using the resulting QoS

to create the DDSDomainParticipant (p. 1139).

When used in DDSDomainParticipantFactory::set default -

participant qos (p. 1222), this special value is used to indicate that the

default QoS should be reset back to the initial value that would be used if the

DDSDomainParticipantFactory::set default participant qos (p. 1222)

operation had never been called.

When used in DDSDomainParticipant::set qos (p. 1197), this special value

is used to indicate that the QoS of the DDSDomainParticipant (p.

1139)

should be changed to match the current default QoS set in the DDSDomain-

ParticipantFactory (p. 1216) that the DDSDomainParticipant (p. 1139)

belongs to.

RTI Connext treats this special value as a constant.

Note: You cannot use this value to get the default QoS values from the Do-

mainParticipant factory; for this purpose, use DDSDomainParticipantFac-

tory::get default participant qos (p. 1224).

See also:

NDDS DISCOVERY PEERS (p. 388)

DDSDomainParticipantFactory::create participant() (p. 1233)

DDSDomainParticipantFactory::set default participant qos()

(p. 1222)

DDSDomainParticipant::set qos() (p. 1197)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

36 Module Documentation

Examples:

HelloWorld publisher.cxx, and HelloWorld subscriber.cxx.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.4 DomainParticipants 37

5.4 DomainParticipants

DDSDomainParticipant (p. 1139) entity and associated elements

Classes

class DDSDomainParticipantListener

<<inter face>> (p. 199) Listener for participant status.

class DDSDomainParticipant

<<inter face>> (p. 199) Container for all DDSDomainEntity ( p. 1138)

objects.

struct DDS DomainParticipantQos

QoS policies supported by a DDSDomainParticipant ( p. 1139) entity.

Variables

struct DDS TopicQos DDS TOPIC QOS DEFAULT

Special value for creating a DDSTopic ( p. 1419) with default QoS.

struct DDS PublisherQos DDS PUBLISHER QOS DEFAULT

Special value for creating a DDSPublisher ( p. 1346) with default QoS.

struct DDS SubscriberQos DDS SUBSCRIBER QOS -

DEFAULT

Special value for creating a DDSSubscriber ( p. 1390) with default QoS.

struct DDS FlowControllerProperty t DDS FLOW -

CONTROLLER PROPERTY DEFAULT

<<eXtension>> (p. 199) Special value for creating a DDSFlowCon-

troller ( p. 1259) with default property.

const char ∗const DDS SQLFILTER NAME

<<eXtension>> (p. 199) The name of the built-in SQL ﬁlter that can be

used with ContentFilteredTopics and MultiChannel DataWriters.

const char ∗const DDS STRINGMATCHFILTER NAME

<<eXtension>> (p. 199) The name of the built-in StringMatch ﬁlter that

can be used with ContentFilteredTopics and MultiChannel DataWriters.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

38 Module Documentation

5.4.1 Detailed Description

DDSDomainParticipant (p. 1139) entity and associated elements

5.4.2 Variable Documentation

5.4.2.1 struct DDS TopicQos DDS TOPIC QOS DEFAULT

Special value for creating a DDSTopic (p. 1419) with default QoS.

When used in DDSDomainParticipant::create topic (p. 1175), this special

value is used to indicate that the DDSTopic (p. 1419) should be created with

the default DDSTopic (p. 1419) QoS by means of the operation get default -

topic qos and using the resulting QoS to create the DDSTopic (p. 1419).

When used in DDSDomainParticipant::set default topic qos (p. 1162),

this special value is used to indicate that the default QoS should be reset back

to the initial value that would be used if the DDSDomainParticipant::set -

default topic qos (p. 1162) operation had never been called.

When used in DDSTopic: :set qos (p. 1421), this special value is used to in-

dicate that the QoS of the DDSTopic (p. 1419) s hould be changed to match

the current default QoS set in the DDSDomainParticipant (p. 1139) that the

DDSTopic (p. 1419) belongs to.

Note: You cannot use this value to get the default QoS values for a Topic; for this

purp os e, use DDSDomainParticipant::get default topic qos (p. 1161).

See also:

DDSDomainParticipant::create topic (p. 1175)

DDSDomainParticipant::set default topic qos (p. 1162)

DDSTopic::set qos (p. 1421)

Examples:

HelloWorld publisher.cxx, and HelloWorld subscriber.cxx.

5.4.2.2 struct DDS PublisherQos DDS PUBLISHER QOS -

DEFAULT

Special value for creating a DDSPublisher (p. 1346) with default QoS.

When used in DDSDomainParticipant::create publisher (p. 1169), this

special value is used to indicate that the DDSPublisher (p. 1346) should be cre-

ated with the default DDSPublisher (p. 1346) QoS by means of the operation

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.4 DomainParticipants 39

get default publisher qos and using the resulting QoS to create the DDSPub-

lisher (p. 1346).

When used in DDSDomainParticipant::set default publisher qos

(p. 1164), this sp e cial value is used to indicate that the default QoS should

be reset back to the initial value that would be used if the DDSDomain-

Participant::set default publisher qos (p. 1164) operation had never been

called.

When used in DDSPublisher::set qos (p. 1366), this special value is used to

indicate that the QoS of the DDSPublisher (p. 1346) should be changed to

match the current default QoS set in the DDSDomainParticipant (p. 1139)

that the DDSPublisher (p. 1346) belongs to.

Note: You cannot use this value to get the default QoS values for a Publisher;

for this purpose, use DDSDomainParticipant::get default publisher qos

(p. 1163).

See also:

DDSDomainParticipant::create publisher (p. 1169)

DDSDomainParticipant::set default publisher qos (p. 1164)

DDSPublisher::set qos (p. 1366)

Examples:

HelloWorld publisher.cxx.

5.4.2.3 struct DDS SubscriberQos DDS SUBSCRIBER QOS -

DEFAULT

Special value for creating a DDSSubscriber (p. 1390) with default QoS.

When used in DDSDomainParticipant::create subscriber (p. 1172), this

special value is used to indicate that the DDSSubscriber (p. 1390) should

be created with the default DDSSubscriber (p. 1390) QoS by means of the

operation get default subscriber qos and using the resulting QoS to c reate the

DDSSubscriber (p. 1390).

When used in DDSDomainParticipant::set default subscrib er qos

(p. 1167), this special value is used to indicate that the default QoS should be

reset back to the initial value that would be used if the DDSDomainPar-

ticipant::set defaul t subscriber qos (p. 1167) operation had never been

called.

When used in DDSSubscriber::set qos (p. 1410), this special value is used to

indicate that the QoS of the DDSSubscriber (p. 1390) should be changed to

match the current default QoS set in the DDSDomainParticipant (p. 1139)

that the DDSSubscriber (p. 1390) belongs to.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

40 Module Documentation

Note: You cannot use this value to get the default QoS values for a Subscriber;

for this purpose, use DDSDomainParticipant::get default subscriber -

qos (p. 1166).

See also:

DDSDomainParticipant::create subscriber (p. 1172)

DDSDomainParticipant::get default subscriber qos (p. 1166)

DDSSubscriber::set qos (p. 1410)

Examples:

HelloWorld subscriber.cxx.

5.4.2.4 struct DDS FlowControllerProperty t

DDS FLOW CONTROLLER PROPERTY DEFAULT

<<eXtension>> ( p. 199) Special value for creating a DDSFlowController

(p. 1259) with default property.

When used in DDSDomainParticipant::create ﬂowcontroller (p. 1184),

this special value is used to indicate that the DDSFlowController (p. 1259)

should be created with the default DDSFlowController (p. 1259) property by

means of the operation get default ﬂowcontroller property and using the result-

ing QoS to create the DDS FlowControllerProperty t (p. 749).

When used in DDSDomainParticipant::set default ﬂowcontroller -

property (p. 1155), this special value is used to indicate that the default

QoS should be reset back to the initial value that would be used if the

DDSDomainParticipant::set default ﬂowcontroller property (p. 1155)

operation had never been called.

When used in DDSFlowController::set property (p. 1260), this special

value is used to indicate that the property of the DDSFlowController

(p. 1259) should be changed to match the current default property set in the

DDSDomainParticipant (p. 1139) that the DDSFlowController (p. 1259)

belongs to.

Note: You cannot use this value to get the default properties for a Flow-

Controller; for this purpose, use DDSDomainParticipant::get defaul t -

ﬂowcontroller property (p. 1154).

See also:

DDSDomainParticipant::create ﬂowcontroller (p. 1184)

DDSDomainParticipant::set default ﬂowcontroller property

(p. 1155)

DDSFlowController::set property (p. 1260)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.4 DomainParticipants 41

5.4.2.5 const char∗ const DDS SQLFILTER NAME

<<eXtension>> ( p. 199) The name of the built-in SQL ﬁlter that can be

used with ContentFilteredTopics and MultiChannel DataWriters.

See also:

Queries and Filters Syntax (p. 208)

5.4.2.6 const char∗ const DDS STRINGMATCHFILTER NAME

<<eXtension>> ( p. 199) The name of the built-in StringMatch ﬁlter that

can be used with ContentFilteredTopics and MultiChannel DataWriters.

The StringMatch Filter is a subset of the SQL ﬁlter; it only supports the

MATCH relational op e rator on a single string ﬁeld.

See also:

Queries and Filters Syntax (p. 208)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

42 Module Documentation

5.5 Built-in Topics

Built-in objects created by RTI Connext but accessible to the application.

Modules

Participant Built-in Topics

Builtin topic for accessing information about the DomainParticipants discov-

ered by RTI Connext.

Topic Built-i n Topics

Builtin topic for accessing information about the Topics discovered by RTI

Connext.

Publication Built-in Topics

Builtin topic for accessing information about the Publications discovered by

RTI Connext.

Subscription Built-in Topics

Builtin topic for accessing information about the Subscriptions discovered by

RTI Connext.

Classes

struct DDS Locator t

<<eXtension>> (p. 199) Type used to represent the addressing information

needed to send a message to an RTPS Endpoint using one of the supported

transports.

struct DDS LocatorSeq

Declares IDL sequence < DDS Locator t ( p. 783) >.

struct DDS ProtocolVersion t

<<eXtension>> (p. 199) Type used to represent the version of the RTPS

protocol.

struct DDS VendorId t

<<eXtension>> (p. 199) Type used to represent the vendor of the service

implementing the RTPS protocol.

struct DDS ProductVersion t

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.5 Built-in Topics 43

<<eXtension>> (p. 199) Type used to represent the current version of RTI

Connext.

struct DDS BuiltinTopicKey t

The key type of the built-in topic types.

struct DDS ContentFilterProperty t

<<eXtension>> (p. 199) Type used to provide all the required information

to enable content ﬁltering.

Deﬁnes

#deﬁne DDS LOCATOR ADDRESS LENGTH MAX 16

Declares length of address ﬁeld in locator.

#deﬁne DDS PROTOCOLVERSION 1 0 { 1, 0 }

The protocol version 1.0.

#deﬁne DDS PROTOCOLVERSION 1 1 { 1, 1 }

The protocol version 1.1.

#deﬁne DDS PROTOCOLVERSION 1 2 { 1, 2 }

The protocol version 1.2.

#deﬁne DDS PROTOCOLVERSION 2 0 { 2, 0 }

The protocol version 2.0.

#deﬁne DDS PROTOCOLVERSION 2 1 { 2, 1 }

The protocol version 2.1.

#deﬁne DDS PROTOCOLVERSION { 2, 1 }

The most recent protocol version. Currently 1.2.

#deﬁne DDS VENDOR ID LENGTH MAX 2

Length of vendor id.

#deﬁne DDS PRODUCTVERSION UNKNOWN { 0, 0, 0, 0 }

The value used when the product version is unknown.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

44 Module Documentation

Variables

struct DDS Locator t DDS LOCATOR INVALID

An invalid locator.

const DDS Long DDS LOCATOR KIND INVALID

Locator of this kind is invalid.

const DDS UnsignedLong DDS LOCATOR PORT INVALID

An invalid port.

const DDS Octet DDS LOCATOR ADDR ESS INVALID [DDS -

LOCATOR ADDRESS LENGTH MAX]

An invalid address.

const DDS Long DDS LOCATOR KIND UDPv4

A locator for a UDPv4 address.

const DDS Long DDS LOCATOR KIND SHMEM

A locator for an address acessed via shared memory.

const DDS Long DDS LOCATOR KIND UDPv6

A locator for a UDPv6 address.

const DDS Long DDS LOCATOR KIND RESERVED

Locator of this kind is reserved.

5.5.1 Detailed Description

Built-in objects created by RTI Connext but accessible to the application.

RTI Connext must discover and keep track of the remote entities, such as new

participants in the domain. This information may also be important to the

application, which may want to react to this discovery, or else access it on

demand.

A set of built-in topics and corresponding DDSDataReader (p. 1087) objects

are introduced to be used by the application to access these discovery informa-

tion.

The information can be accessed as if it was normal application data. This allows

the application to know when there are any changes in those values by means

of the DDSListener (p. 1318) or the DDSCondition (p. 1075) mechanisms.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.5 Built-in Topics 45

The built-in data-readers all belong to a built-in DDSSubscriber (p. 1390),

which can be retrieved by using the method DDSDomainParticipant::get -

builtin subscriber (p. 1186). The built-in DDSDataReader (p. 1087) ob-

jects can be retrieved by using the operation DDSSubscriber::lookup -

datareader (p. 1404), with the topic name as a parameter.

Built-in entities have default listener settings as well. The built-in DDSSub-

scriber (p. 1390) and all of its built-in topics have ’nil’ listeners with all statuses

appearing in their listener masks (acting as a NO-OP listener that does not reset

communication status). The built-in DataReaders have null listeners with no

statuses in their masks.

The information that is accessible about the remote entities by means of the

built-in topics includes all the QoS policies that apply to the corresponding

remote Entity. This QoS policies appear as normal ’data’ ﬁelds inside the data

read by means of the built-in Topic. Additional information is provided to

identify the Entity and facilitate the application logic.

The built-in DDSDataReader (p. 1087) will not provide data pertaining to

entities created from the same DDSDomainParticipant (p. 1139) under the

assumption that such entities are already known to the application that created

them.

Refer to DDS ParticipantBuiltinTopicData (p. 816), DDS -

TopicBuiltinTopicData (p. 958), DDS SubscriptionBuiltinTopicData

(p. 936) and DDS PublicationBuiltinTopicData (p. 839) for a description

of all the built-in topics and their contents.

The QoS of the built-in DDSSubscriber (p. 1390) and DDSDataReader

(p. 1087) objects is given by the following table:

5.5.2 Deﬁne Documentation

5.5.2.1 #deﬁne DDS LOCATOR ADDRESS LENGTH MAX 16

Declares length of address ﬁeld in locator.

5.5.2.2 #deﬁne DDS PROTOCOLVERSION 1 0 { 1, 0 }

The protocol version 1.0.

5.5.2.3 #deﬁne DDS PROTOCOLVERSION 1 1 { 1, 1 }

The protocol version 1.1.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

46 Module Documentation

5.5.2.4 #deﬁne DDS PROTOCOLVERSION 1 2 { 1, 2 }

The protocol version 1.2.

5.5.2.5 #deﬁne DDS PROTOCOLVERSION 2 0 { 2, 0 }

The protocol version 2.0.

5.5.2.6 #deﬁne DDS PROTOCOLVERSION 2 1 { 2, 1 }

The protocol version 2.1.

5.5.2.7 #deﬁne DDS PROTOCOLVERSION { 2, 1 }

The most recent protocol version. Currently 1.2.

5.5.2.8 #deﬁne DDS VENDOR ID LENGTH MAX 2

Length of vendor id.

5.5.2.9 #deﬁne DDS PRODUCTVERSION UNKNOWN { 0, 0, 0,

0 }

The value used when the product version is unknown.

5.5.3 Variable Documentation

5.5.3.1 struct DDS Locator t DDS LOCATOR INVALID

An invalid locator.

5.5.3.2 const DDS

Long DDS LOCATOR KIND INVALID

Locator of this kind is invalid.

5.5.3.3 const DDS UnsignedLong DDS LOCATOR PORT -

INVALID

An invalid port.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.5 Built-in Topics 47

5.5.3.4 const DDS Octet DDS LOCATOR ADDRESS -

INVALID[DDS LOCATOR ADDRESS LENGTH MAX]

An invalid address.

5.5.3.5 const DDS Long DDS LOCATOR KIND UDPv4

A locator for a UDPv4 address.

5.5.3.6 const DDS Long DDS LOCATOR KIND SHMEM

A locator for an address acessed via shared memory.

5.5.3.7 const DDS Long DDS LOCATOR KIND UDPv6

A locator for a UDPv6 address.

5.5.3.8 const DDS Long DDS LOCATOR KIND RESERV ED

Locator of this kind is reserved.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

48 Module Documentation

QoS Value

DDS UserDataQosPolicy

(p. 1048)

0-length sequence

DDS TopicDataQosPolicy

(p. 963)

0-length sequence

DDS GroupDataQosPolicy

(p. 755)

0-length sequence

DDS DurabilityQosPolicy

(p. 614)

DDS TRANSIENT LOCAL -

DURABILITY QOS

(p. 349)

DDS -

DurabilityServiceQosPolicy

(p. 618)

Does not apply as

DDS DurabilityQosPolicyKind

(p. 348) is DDS TRANSIENT -

LOCAL DURABILITY QOS

(p. 349)

DDS PresentationQosPolicy

(p. 823)

access scope = DDS TOPIC -

PRESENTATION QOS (p. 352)

coherent access =

DDS BOOLEAN FALSE

(p. 299) ordered access =

DDS BOOLEAN FALSE

(p. 299)

DDS DeadlineQosPolicy (p. 567) Period = inﬁnite

DDS LatencyBudgetQosPolicy

(p. 771)

duration = 0

DDS OwnershipQosPolicy

(p. 807)

DDS SHARED -

OWNERSHIP QOS

(p. 356)

DDS -

OwnershipStrengthQosPolicy

(p. 814)

value = 0

DDS LivelinessQosPolicy

(p. 779)

kind = DDS AUTOMATIC -

LIVELINESS QOS (p. 359)

lease duration = 0

DDS -

TimeBasedFilterQosPolicy

(p. 954)

minimum separation = 0

DDS PartitionQosPolicy (p. 820) 0-length sequence

DDS ReliabilityQosPolicy

(p. 865)

kind = DDS RELIABLE -

RELIABILITY QOS (p. 363)

max blocking time = 100

milliseconds

DDS -

DestinationOrderQosPolicy

(p. 570)

DDS BY RECEPTION -

TIMESTAMP -

DESTINATIONORDER QOS

(p. 366)

DDS HistoryQosPolicy (p. 758) kind = DDS KEEP LAST -

HISTORY QOS (p. 368) depth =

DDS ResourceLimitsQosPolicy

(p. 879)

max samples =

DDS LENGTH UNLIMITED

(p. 371) max instances =

DDS LENGTH UNLIMITED

(p. 371) max samples per instance =

DDS LENGTH UNLIMITED

(p. 371)

DDS -

ReaderDataLifecycleQosPolicy

(p. 859)

autopurge nowriter samples delay =

inﬁnite

autopurge disposed samples delay =

inﬁnite

DDS EntityFactoryQosPolicy

(p. 733)

autoenable created entities =

DDS BOOLEAN TRUE (p. 298)

Table 5.2: QoS of built-in DDSSubscriber ( p. 1390) and DDSDataReader

( p. 1087)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.6 Topic Module 49

5.6 Topic Module

Contains the DDSTopic (p. 1419), DDSContentFilteredTopic (p. 1081),

and DDSMultiTopic (p. 1322) classes, the DDSTopicListener (p. 1430) in-

terface, and more generally, all that is needed by an application to deﬁne

DDSTopic (p. 1419) objects and attach QoS policies to them.

Modules

Topics

DDSTopic ( p. 1419) entity and associated elements

User Data Type Support

Deﬁnes generic classes and macros to support user data types.

Type Code Support

<<eXtension>> (p. 199) A DDS TypeCode (p. 992) is a mechanism for

representing a type at runtime. RTI Connext can use type codes to send type

deﬁnitions on the network. You will need to understand this API in order to

use the Dynamic Data ( p. 77) capability or to inspect the type information

you receive from remote readers and writers.

Built-in Types

<<eXtension>> (p. 199) RTI Connext provides a set of very simple data

types for you to use with the topics in your application.

Dynamic Data

<<eXtension>> (p. 199) The Dynamic Data API provides a way to inter-

act with arbitrarily complex data types at runtime without the need for code

generation.

DDS-Speciﬁc Primitive Types

Basic DDS value types for use in user data types.

5.6.1 Detailed Description

Contains the DDSTopic (p. 1419), DDSContentFilteredTopic (p. 1081),

and DDSMultiTopic (p. 1322) classes, the DDSTopicListener (p. 1430) in-

terface, and more generally, all that is needed by an application to deﬁne

DDSTopic (p. 1419) objects and attach QoS policies to them.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

50 Module Documentation

5.7 Topics

DDSTopic (p. 1419) entity and associated elements

Classes

class DDSTopicDescription

<<inter face>> (p. 199) Base class for DDSTopic ( p. 1419), DDSCon-

tentFilteredTopic ( p. 1081), and DDSMultiTopic ( p. 1322).

class DDSContentFilteredTopic

<<inter face>> (p. 199) Specialization of DDSTopicDescription

( p. 1427) that allows for content-based subscriptions.

class DDSMultiTopic

[Not supported (optional)] <<interface>> (p. 199) A specialization

of DDSTopicDescription ( p. 1427) that allows subscriptions that com-

bine/ﬁlter/rearrange data coming from several topics.

class DDSTopic

<<inter face>> (p. 199) The most basic description of the data to be pub-

lished and subscribed.

class DDSTopicListener

<<inter face>> (p. 199) DDSListener ( p. 1318) for DDSTopic ( p. 1419)

entities.

class DDSContentFilter

<<inter face>> (p. 199) Interface to be used by a custom ﬁlter of a

DDSContentFilteredTopic ( p. 1081)

struct DDS InconsistentTopicStatus

DDS INCONSISTENT TOPIC STATUS ( p. 322)

struct DDS TopicQos

QoS policies supported by a DDSTopic ( p. 1419) entity.

5.7.1 Detailed Description

DDSTopic (p. 1419) entity and associated elements

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.8 User Data Type Support 51

5.8 User Data Type Support

Deﬁnes generic classes and macros to support user data types.

Classes

struct FooTypeSupport

<<inter face>> (p. 199) <<generic>> (p. 199) User data type speciﬁc in-

terface.

class DDSTypeSupport

<<inter face>> (p. 199) An abstract marker interface that has to be spe-

cialized for each concrete user data type that will be used by the application.

struct Foo

A representative user-deﬁned data type.

struct DDS InstanceHandleSeq

Instantiates FooSeq (p. 1494) < DDS InstanceHandle t ( p. 53) > .

Deﬁnes

#deﬁne DDS TYPESUPPORT CPP(TTypeSupport, TData)

Declares the interface required to support a user data type.

#deﬁne DDS DATAWRITER CPP METP(TDataWriter, TData)

Declares the interface required to support a user data type speciﬁc data writer.

#deﬁne DDS DATAREADER CPP METP(TDataReader,

TDataSeq, TData)

Declares the interface required to support a user data type-speciﬁc data

reader.

Typedefs

typedef DDS HANDLE TYPE NATIVE DDS InstanceHandle t

Type deﬁnition for an instance handle.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

52 Module Documentation

Functions

DDS Boolean DDS InstanceHandle equals (const DDS -

InstanceHandle t ∗self, const DDS InstanceHandle t ∗other)

Compares this instance handle with another handle for equality.

DDS Boolean DDS InstanceHandle is nil (const DDS -

InstanceHandle t ∗self)

Compare this handle to DDS HANDLE NIL ( p. 55).

Variables

const DDS InstanceHandle t DDS HANDLE NIL

The NIL instance handle.

5.8.1 Detailed Description

Deﬁnes generic classes and macros to support user data types.

DDS speciﬁes strongly typed interfaces to read and write user data. For each

data class deﬁned by the application, there is a number of specialised classes

that are required to facilitate the type-safe interaction of the application with

RTI Connext.

RTI Connext provides an automatic means to generate all these type-speciﬁc

classes with the rtiddsgen (p. 220) utility. The complete set of automatic

classes created for a hypothetical user data type named Foo (p. 1443) are shown

below.

The macros deﬁned here declare the strongly typed APIs needed to support an

arbitrary user deﬁned data of type Foo (p. 1443).

See also:

rtiddsgen (p. 220)

5.8.2 Deﬁne Documentation

5.8.2.1 #deﬁne DDS TYPESUPPORT CPP(TTypeSupport,

TData)

Declares the interface required to support a user data type.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.8 User Data Type Support 53

Deﬁnes:

FooTypeSupport ( p. 1509) TypeSupport of type Foo (p. 1443), i.e.

FooTypeSupport (p. 1509)

Examples:

HelloWorldSupport.cxx.

5.8.2.2 #deﬁne DDS DATAWRITER CPP METP(TDataWriter,

TData)

Declares the interface required to support a user data type speciﬁc data writer.

Uses:

FooTypeSupport ( p. 1509) user data type, Foo (p. 1443)

Deﬁnes:

FooDataWriter ( p. 1475) DDSDataWriter (p. 1113) of type Foo

(p. 1443), i.e. FooDataWriter (p. 1475)

5.8.2.3 #deﬁne DDS DATAREADER CPP METP(TDataReader,

TDataSeq, TData)

Declares the interface required to support a user data type-speciﬁc data reader.

Uses:

FooTypeSupport ( p. 1509) user data type, Foo (p. 1443) FooSeq

(p. 1494) sequence of user data type, sequence<::Foo>

Deﬁnes:

FooDataReader ( p. 1444) DDSDataReader (p. 1087) of type Foo

(p. 1443), i.e. FooDataReader (p. 1444)

See also:

FooSeq (p. 1494)

5.8.3 Typedef Documentation

5.8.3.1 typedef DDS HANDLE TYPE NATIVE

DDS InstanceHandle t

Type deﬁnition for an instance handle.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

54 Module Documentation

Handle to identiy diﬀerent instances of the same DDSTopic (p. 1419) of a

certain type.

See also:

FooDataWriter::register instance (p. 1478)

DDS SampleInfo::instance handle (p. 917)

Examples:

HelloWorld publisher.cxx.

5.8.4 Function Documentation

5.8.4.1 DDS Boolean DDS InstanceHandle equals (const

DDS InstanceHandle t ∗ self, const DDS InstanceHandle t

∗ other)

Compares this instance handle with another handle for equality.

Parameters:

self <<in>> ( p. 200) This handle. Cannot be NULL.

other <<in>> ( p. 200) The other handle to be compared with this han-

dle. Cannot be NULL.

Returns:

DDS BOOLEAN TRUE (p. 298) if the two handles have equal values,

or DDS BOOLEAN FALSE (p. 299) otherwise.

See also:

DDS InstanceHandle is nil (p. 54)

5.8.4.2 DDS

Boolean DDS InstanceHandle is nil (const

DDS InstanceHandle t ∗ self)

Compare this handle to DDS HANDLE NIL (p. 55).

Returns:

DDS BOOLEAN TRUE (p. 298) if the given instance handle is equal

to DDS HANDLE NIL (p. 55) or DDS BOOLEAN FALSE (p. 299)

otherwise.

See also:

DDS InstanceHandle equals (p. 54)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.8 User Data Type Support 55

5.8.5 Variable Documentation

5.8.5.1 const DDS InstanceHandle t DDS HANDLE NIL

The NIL instance handle.

Special DDS InstanceHandle t (p. 53) value

See also:

DDS InstanceHandle is nil (p. 54)

Examples:

HelloWorld publisher.cxx.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

56 Module Documentation

5.9 Type Code Support

<<eXtension>> ( p. 199) A DDS TypeCode ( p. 992) is a mechanism for

representing a type at runtime. RTI Connext can use type codes to send type

deﬁnitions on the network. You will need to understand this API in order to

use the Dynamic Data (p. 77) capability or to inspect the type information

you receive from remote readers and writers.

Classes

struct DDS TypeCode

The deﬁnition of a particular data type, which you can use to inspect the

name, members, and other properties of types generated with rtiddsgen

( p. 220) or to modify types you deﬁne yourself at runtime.

struct DDS StructMember

A description of a member of a struct.

struct DDS StructMemberSeq

Deﬁnes a sequence of struct members.

struct DDS UnionMember

A description of a member of a union.

struct DDS UnionMemberSeq

Deﬁnes a sequence of union members.

struct DDS EnumMember

A description of a member of an enumeration.

struct DDS EnumMemberSeq

Deﬁnes a sequence of enumerator members.

struct DDS ValueMember

A description of a member of a value type.

struct DDS ValueMemberSeq

Deﬁnes a sequence of value members.

struct DDS TypeCodeFactory

A singleton factory for creating, copying, and deleting data type deﬁnitions

dynamically.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.9 Type Code Support 57

Deﬁnes

#deﬁne DDS TYPECODE MEMBER ID INVALID

A sentinel indicating an invalid DDS TypeCode ( p. 992) member ID.

#deﬁne DDS TYPECODE INDEX INVALID

A sentinel indicating an invalid DDS TypeCode ( p. 992) member index.

#deﬁne DDS TYPECODE NOT BITFIELD

Indicates that a member of a type is not a bitﬁeld.

#deﬁne DDS VM NONE

Constant used to indicate that a value type has no modiﬁers.

#deﬁne DDS VM CUSTOM

Constant used to indicate that a value type has the custom modiﬁer.

#deﬁne DDS VM ABSTRACT

Constant used to indicate that a value type has the abstract modiﬁer.

#deﬁne DDS VM TRUNCATABLE

Constant used to indicate that a value type has the truncatable modiﬁer.

#deﬁne DDS PRIVATE MEMBER

Constant used to indicate that a value type member is private.

#deﬁne DDS PUBLIC MEMBER

Constant used to indicate that a value type member is public.

#deﬁne DDS TYPECODE NONKEY MEMBER

A ﬂag indicating that a type member is optional and not part of the key.

#deﬁne DDS TYPECODE KEY MEMBER

A ﬂag indicating that a type member is part of the key for that type, and

therefore required.

#deﬁne DDS TYPECODE NONKEY REQUIRED MEMBER

A ﬂag indicating that a type member is not part of the key but is nevertheless

required.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

58 Module Documentation

Typedefs

typedef short DDS ValueModiﬁer

Modiﬁer type for a value type.

typedef short DDS Visibility

Type to indicate the visibility of a value type member.

Enumerations

enum DDS TCKind {

DDS

TK NULL,

DDS TK SHORT,

DDS TK LONG,

DDS TK USHORT,

DDS TK ULONG,

DDS TK FLOAT,

DDS TK DOUBLE,

DDS TK BOOLEAN,

DDS TK CHAR,

DDS TK OCTET,

DDS TK STRUCT,

DDS TK UNION,

DDS TK ENUM,

DDS TK STRING,

DDS TK SEQUENCE,

DDS TK ARRAY,

DDS TK ALIAS,

DDS TK LONGLONG,

DDS TK ULONGLONG,

DDS TK LONGDOUBLE,

DDS TK WCHAR,

DDS TK WSTRING,

DDS TK VALUE,

DDS TK SPARSE }

Enumeration type for DDS TypeCode ( p. 992) kinds.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.9 Type Code Support 59

enum DDS ExtensibilityKind {

DDS FINAL EXTENSIBILITY,

DDS EXTENSIBLE EXTENSIBILITY,

DDS MUTABLE EXTENSIBILITY }

Type to indicate the extensibility of a type.

Variables

DDS TypeCode DDS g tc null

Basic NULL type.

DDS TypeCode DDS g tc long

Basic 32-bit signed integer type.

DDS TypeCode DDS g tc ushort

Basic unsigned 16-bit integer type.

DDS TypeCode DDS g tc ulong

Basic unsigned 32-bit integer type.

DDS TypeCode DDS g tc ﬂoat

Basic 32-bit ﬂoating point type.

DDS TypeCode DDS g tc double

Basic 64-bit ﬂoating point type.

DDS TypeCode DDS g tc boolean

Basic Boolean type.

DDS TypeCode DDS g tc octet

Basic octet/byte type.

DDS TypeCode DDS g tc longlong

Basic 64-bit integer type.

DDS TypeCode DDS g tc ulonglong

Basic unsigned 64-bit integer type.

DDS TypeCode DDS g tc longdouble

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

60 Module Documentation

Basic 128-bit ﬂoating point type.

DDS TypeCode DDS g tc wchar

Basic four-byte character type.

5.9.1 Detailed Description

<<eXtension>> ( p. 199) A DDS TypeCode ( p. 992) is a mechanism for

representing a type at runtime. RTI Connext can use type codes to send type

deﬁnitions on the network. You will need to understand this API in order to

use the Dynamic Data (p. 77) capability or to inspect the type information

you receive from remote readers and writers.

Type codes are values that are used to describe arbitrarily complex types at

runtime. Type code values are manipulated via the DDS TypeCode (p. 992)

class, which has an analogue in CORBA.

A DDS TypeCode (p. 992) value c onsists of a type co de kind (represented by

the DDS TCKind (p. 66) enumeration) and a list of members (that is, ﬁelds).

These members are recursive: each one has its own DDS TypeCode (p. 992),

and in the case of complex types (structures, arrays, and so on), these contained

type codes contain their own members.

There are a number of uses for type codes. The type code mechanism can be used

to unambiguously match type representations. The DDS TypeCode::equal

(p. 998) method is a more reliable test than comparing the string type names,

requiring equivalent deﬁnitions of the types.

5.9.2 Accessing a Local ::DDS TypeCode

When generating types with rtiddsgen (p. 220), type codes are enabled by

default. (The -notypecode option can be used to disable generation of DDS -

TypeCode (p. 992) information.) For these types, a DDS TypeCode (p. 992)

may be accessed by calling the Foo get typecode function for a type ”Foo”,

which returns a DDS TypeCode (p. 992) pointer.

This API also includes support for dynamic creation of DDS TypeCode

(p. 992) values, typically for use with the Dynamic Data (p. 77) API. You

can create a DDS TypeCode (p. 992) using the DDS TypeCodeFactory

(p. 1022) class. You will construct the DDS TypeCode (p. 992) recursively,

from the outside in: start with the type codes for primitive types, then compose

them into complex types like arrays, structures, and so on. You will ﬁnd the

follow ing methods helpful:

DDS TypeCodeFactory::get primitive tc (p. 1026), which provides

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.9 Type Code Support 61

the DDS TypeCode (p. 992) instances corresponding to the primitive

types (e.g. DDS TK LONG (p. 66), DDS TK SHORT (p. 66), and

so on).

DDS TypeCodeFactory::create string tc (p. 1033) and DDS -

TypeCodeFactory::create wstring tc (p. 1034) create a DDS -

TypeCode (p. 992) representing a text string with a certain bound (i.e.

maximum length).

DDS TypeCodeFactory::create array tc (p. 1035) and DDS -

TypeCodeFactory::create sequence tc (p. 1034) create a DDS -

TypeCode (p. 992) for a collection based on the DDS TypeCode

(p. 992) for its elements.

DDS TypeCodeFactory::create struct tc (p. 1027), DDS -

TypeCodeFactory::create value tc (p. 1028), and DDS -

TypeCodeFactory::create sparse tc (p. 1036) create a DDS -

TypeCode (p. 992) for a structured type.

5.9.3 Accessing a Remote ::DDS TypeCode

In addition to being used locally, RTI Connext can transmit DDS TypeCode

(p. 992) on the network b etween participants. This information can be used to

access information about types used remotely at runtime, for example to be

able to publish or subscribe to topics of arbitrarily types (see Dynamic Data

(p. 77)). This functionality is useful for a generic system monitoring tool like

rtiddsspy.

Remote DDS TypeCode (p. 992) information is shared during discovery over

the publication and subscription built-in topics and can be accessed using

the built-in readers for these topics; see Built-in Topics (p. 42). Discov-

ered DDS TypeCode (p. 992) values are not cached by RTI Connext upon

receipt and are therefore not available from the built-in topic data returned

by DDSDataWriter::get matched subscription data (p. 1124) or DDS-

DataReader::get matched publication data (p. 1097).

The space available locally to deserialize a discovered remote DDS -

TypeCode (p. 992) is speciﬁed by the DDSDomainParticipant (p. 1139)’s

DDS DomainParticipantResourceLimitsQosPolicy::type code max -

serialized length (p. 608) QoS parameter. To support especially complex

type codes, it may be necessary for you to increase the value of this parameter.

See also:

DDS TypeCode (p. 992)

Dynamic Data (p. 77)

rtiddsgen (p. 220)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

62 Module Documentation

DDS SubscriptionBuiltinTopicData (p. 936)

DDS PublicationBuiltinTopicData (p. 839)

5.9.4 Deﬁne Documentation

5.9.4.1 #deﬁne DDS TYPECODE MEMBER ID INVALID

A sentinel indicating an invalid DDS TypeCode (p. 992) member ID.

5.9.4.2 #deﬁne DDS TYPECODE INDEX INVALID

A sentinel indicating an invalid DDS TypeCode (p. 992) member index.

5.9.4.3 #deﬁne DDS TYPECODE NOT BITFIELD

Indicates that a member of a type is not a bitﬁeld.

5.9.4.4 #deﬁne DDS VM NONE

Constant used to indicate that a value type has no modiﬁers.

See also:

DDS ValueModiﬁer (p. 65)

Examples:

HelloWorld.cxx.

5.9.4.5 #deﬁne DDS VM CUSTOM

Constant used to indicate that a value type has the custom modiﬁer.

This modiﬁer is used to specify whether the value type uses custom marshaling.

See also:

DDS ValueModiﬁer (p. 65)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.9 Type Code Support 63

5.9.4.6 #deﬁne DDS VM ABSTRACT

Constant used to indicate that a value type has the abstract modiﬁer.

An abstract value type may not be instantiated.

See also:

DDS ValueModiﬁer (p. 65)

5.9.4.7 #deﬁne DDS VM TRUNCATABLE

Constant used to indicate that a value type has the truncatable modiﬁer.

A value with a state that derives from another value with a state can be declared

as truncatable. A truncatable type means the object c an be truncated to the

base type.

See also:

DDS ValueModiﬁer (p. 65)

5.9.4.8 #deﬁne DDS PRIVATE MEMBER

Constant used to indicate that a value type member is private.

See also:

DDS Visibility (p. 66)

DDS PUBLIC MEMBER (p. 63)

Examples:

HelloWorld.cxx.

5.9.4.9 #deﬁne DDS PUBLIC MEMBER

Constant used to indicate that a value type member is public.

See also:

DDS Visibility (p. 66)

DDS PRIVATE MEMBER (p. 63)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

64 Module Documentation

5.9.4.10 #deﬁne DDS TYPECODE NONKEY MEMBER

A ﬂag indicating that a type member is optional and not part of the key.

Only sparse value types (i.e. types of DDS TCKind (p. 66) DDS -

TK SPA RSE (p. 67)) support this ﬂag. Non-key members of other type

kinds should use the ﬂag DDS TYPECODE NONKEY REQUIRED -

MEMBER (p. 65).

If a type is used with the Dynamic Data (p. 77) facility, a DDS -

DynamicData (p. 622) sample of the type will only c ontain a value for a

DDS TYPECODE NONKEY MEMBER (p. 64) ﬁeld if one has been ex-

plicitly set (see, for example, DDS DynamicData::set long (p. 687)). The

middleware will not assume any default value.

See also:

DDS TYPECODE KEY MEMBER (p. 64)

DDS TYPECODE NONKEY REQUIRED MEMBER (p. 65)

DDS TYPECODE KEY MEMBER (p. 64)

DDS TypeCode::add member (p. 1017)

DDS TypeCode::add member ex (p. 1019)

DDS TypeCode::is member key (p. 1005)

DDS TypeCode::is member required (p. 1005)

DDS StructMember::is key (p. 932)

DDS ValueMember::i s key (p. 1051)

5.9.4.11 #deﬁne DDS TYPECODE KEY MEMBER

A ﬂag indicating that a type membe r is part of the key for that type, and

therefore required.

If a type is used with the Dynamic Data (p. 77) facility, all DDS -

DynamicData (p. 622) samples of the type will contain a value for all DDS -

TYPECODE KEY MEMBER (p. 64) ﬁelds, even if the type is a sparse

value type (i.e. of kind DDS TK SPARSE (p. 67)). If you do not set a value

of the member explicitly (see, for example, DDS DynamicData::set long

(p. 687)), the middleware will assume a default ”zero” value: numeric values

will be set to zero; strings and sequences will be of zero length.

See also:

DDS TYPECODE NONKEY REQUIRED MEMBER (p. 65)

DDS TYPECODE NONKEY MEMBER (p. 64)

DDS TypeCode::add member (p. 1017)

DDS TypeCode::add member ex (p. 1019)

DDS TypeCode::is member key (p. 1005)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.9 Type Code Support 65

DDS TypeCode::is member required (p. 1005)

DDS StructMember::is key (p. 932)

DDS ValueMember::i s key (p. 1051)

5.9.4.12 #deﬁne DDS TYPECODE NONKEY REQUIRED -

MEMBER

A ﬂag indicating that a type member is not part of the key but is nevertheless

required.

This is the most common kind of member.

If a type is used with the Dynamic Data (p. 77) facility, all DDS -

DynamicData (p. 622) samples of the type will contain a value for all DDS -

TYPECODE NONKEY REQUIRED MEMBER (p. 65) ﬁelds, even if

the type is a sparse value type (i.e. of kind DDS TK SPARSE (p. 67)). If

you do not set a value of the member explicitly (see, for example, DDS -

DynamicData::set long (p. 687)), the middleware will assume a default

”zero” value: numeric values will be set to zero; strings and sequences will

be of zero length.

See also:

DDS TYPECODE KEY MEMBER (p. 64)

DDS TYPECODE NONKEY MEMBER (p. 64)

DDS TYPECODE KEY MEMBER (p. 64)

DDS TypeCode::add member (p. 1017)

DDS TypeCode::add member ex (p. 1019)

DDS TypeCode::is member key (p. 1005)

DDS TypeCode::is member required (p. 1005)

DDS StructMember::is key (p. 932)

DDS ValueMember::i s key (p. 1051)

5.9.5 Typedef Documentation

5.9.5.1 typedef short DDS ValueModiﬁer

Modiﬁer type for a value type.

See also:

DDS VM NONE (p. 62)

DDS VM CUSTOM (p. 62)

DDS VM ABSTRACT (p. 63)

DDS VM TRUNCATABLE (p. 63)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

66 Module Documentation

5.9.5.2 typedef short DDS Visibility

Type to indicate the visibility of a value type member.

See also:

DDS PRIVATE MEMBER (p. 63)

DDS PUBLIC MEMBER (p. 63)

5.9.6 Enumeration Type Documentation

5.9.6.1 enum DDS TCKind

Enume ration type for DDS TypeCode (p. 992) kinds.

Type code kinds are modeled as values of this type.

Enumerator:

DDS TK NULL Indicates that a type code does not describe anything.

DDS TK SHORT short type.

DDS TK LONG long type.

DDS TK USHORT unsigned short type.

DDS TK ULONG unsigned long type.

DDS TK FLOAT ﬂoat type.

DDS TK DOUBLE double type.

DDS TK BOOLEAN boolean type.

DDS TK CHAR char type.

DDS TK OCTET octet type.

DDS TK STRUCT struct type.

DDS TK UNION union type.

DDS TK ENUM enumerated type.

DDS TK STRING string type.

DDS TK SEQUENCE sequence type.

DDS TK ARRAY array type.

DDS TK ALIAS alias (typedef) type.

DDS TK LONGLONG long long type.

DDS TK ULONGLONG unsigned long long type.

DDS TK LONGDOUBLE long double type.

DDS TK WCHAR wide char type.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.9 Type Code Support 67

DDS TK WSTRING wide string type.

DDS TK VALUE value type.

DDS TK SPARSE A sparse value type.

A sparse value type is one in which all of the ﬁelds are not necessarily

sent on the network as a part of every sample.

Fields of a sparse value type fall into one of three categories:

Key ﬁelds (see DDS TYPECODE KEY MEMBER (p. 64))

Non-key, but required members (see DDS TYPECODE -

NONKEY REQUIRED MEMBER (p. 65))

Non-key, optional members (see DDS TYPECODE -

NONKEY MEMBER (p. 64))

Fields of the ﬁrst two kinds must appear in every sample. These are

also the only kinds of ﬁelds on which you can perform content ﬁltering

(see DDSContentFilteredTopic (p. 1081)), because ﬁlter evaluation

on a non-existent ﬁeld is not well deﬁned.

5.9.6.2 enum DDS ExtensibilityKind

Type to indicate the extensibility of a type.

Enumerator:

DDS FINAL EXTENSIBILITY Speciﬁes that a type has FINAL ex-

tensibility.

A type may be ﬁnal, indicating that the range of its possible values

is strictly deﬁned. In particular, it is not possible to add elements

to members of collection or aggregate d types while maintaining type

assignability.

The following types are always ﬁnal:

DDS TK ARRAY (p. 66)

All primitive types

DDS EXTENSIBLE EXTENSIBILITY Speciﬁes that a type has

EXTENSIBLE extensibility.

A type may be extensible, indicating that two types, where one c on-

tains all of the elements/members of the other plus additional ele-

ments/members appended to the end, may remain assignable.

DDS MUTABLE EXTENSIBILITY Speciﬁes that a type has MU-

TABLE extensibility.

[Not supported.]

A type may be mutable, indicating that two types may diﬀer from

one another in the additional, removal, and/or transposition of ele-

ments/members while remaining assignable.

The following types are always mutable:

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

68 Module Documentation

DDS TK SEQUENCE (p. 66)

DDS TK STRING (p. 66)

DDS TK WSTRING (p. 67)

The support for type mutability in this release is limited to DDS -

TK SEQUENCE (p. 66), DDS TK STRING (p. 66), and DDS -

TK WSTRING (p. 67).

Mutability in DDS TK STRUCT (p. 66), DDS TK UNION

(p. 66), DDS TK VALUE (p. 67), and DDS TK ENUM (p. 66)

is not supported.

5.9.7 Variable Documentation

5.9.7.1 DDS TypeCode DDS g tc null

Basic NULL type.

For new code, DDS TypeCodeFactory::get primitive tc (p. 1026) is pre-

ferred to using this global variable.

See also:

DDS TypeCodeFactory::get primitive tc (p. 1026)

5.9.7.2 DDS TypeCode DDS g tc long

Basic 32-bit signed integer type.

For new code, DDS TypeCodeFactory::get primitive tc (p. 1026) is pre-

ferred to using this global variable.

See also:

DDS TypeCodeFactory::get primitive tc (p. 1026)

DDS Long (p. 300)

5.9.7.3 DDS TypeCode DDS g tc ushort

Basic unsigned 16-bit integer type.

For new code, DDS TypeCodeFactory::get primitive tc (p. 1026) is pre-

ferred to using this global variable.

See also:

DDS TypeCodeFactory::get primitive tc (p. 1026)

DDS UnsignedShort (p. 299)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.9 Type Code Support 69

5.9.7.4 DDS TypeCode DDS g tc ulong

Basic unsigned 32-bit integer type.

For new code, DDS TypeCodeFactory::get primitive tc (p. 1026) is pre-

ferred to using this global variable.

See also:

DDS TypeCodeFactory::get primitive tc (p. 1026)

DDS UnsignedLong (p. 300)

5.9.7.5 DDS TypeCode DDS g tc ﬂoat

Basic 32-bit ﬂoating point type.

For new code, DDS TypeCodeFactory::get primitive tc (p. 1026) is pre-

ferred to using this global variable.

See also:

DDS TypeCodeFactory::get primitive tc (p. 1026)

DDS Float (p. 300)

5.9.7.6 DDS TypeCode DDS g tc double

Basic 64-bit ﬂoating point type.

For new code, DDS TypeCodeFactory::get primitive tc (p. 1026) is pre-

ferred to using this global variable.

See also:

DDS TypeCodeFactory::get primitive tc (p. 1026)

DDS Double (p. 300)

5.9.7.7 DDS TypeCode DDS g tc boolean

Basic Boolean type.

For new code, DDS TypeCodeFactory::get primitive tc (p. 1026) is pre-

ferred to using this global variable.

See also:

DDS TypeCodeFactory::get primitive tc (p. 1026)

DDS Boolean (p. 301)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

70 Module Documentation

5.9.7.8 DDS TypeCode DDS g tc octet

Basic octet/byte type.

For new code, DDS TypeCodeFactory::get primitive tc (p. 1026) is pre-

ferred to using this global variable.

See also:

DDS TypeCodeFactory::get primitive tc (p. 1026)

DDS Octet (p. 299)

5.9.7.9 DDS TypeCode DDS g tc longlong

Basic 64-bit integer type.

For new code, DDS TypeCodeFactory::get primitive tc (p. 1026) is pre-

ferred to using this global variable.

See also:

DDS TypeCodeFactory::get primitive tc (p. 1026)

DDS LongLong (p. 300)

5.9.7.10 DDS TypeCode DDS g tc ulonglong

Basic unsigned 64-bit integer type.

For new code, DDS TypeCodeFactory::get primitive tc (p. 1026) is pre-

ferred to using this global variable.

See also:

DDS TypeCodeFactory::get primitive tc (p. 1026)

DDS UnsignedLongLong (p. 300)

5.9.7.11 DDS TypeCode DDS g tc longdouble

Basic 128-bit ﬂoating point type.

For new code, DDS TypeCodeFactory::get primitive tc (p. 1026) is pre-

ferred to using this global variable.

See also:

DDS TypeCodeFactory::get primitive tc (p. 1026)

DDS LongDouble (p. 300)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.9 Type Code Support 71

5.9.7.12 DDS TypeCode DDS g tc wchar

Basic four-byte character type.

For new code, DDS TypeCodeFactory::get primitive tc (p. 1026) is pre-

ferred to using this global variable.

See also:

DDS TypeCodeFactory::get primitive tc (p. 1026)

DDS Wchar (p. 299)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

72 Module Documentation

5.10 Built-in Types

<<eXtension>> ( p. 199) RTI Connext provides a set of very simple data

types for you to use with the topics in your application.

Modules

String Built-in Type

Built-in type consisting of a singl e character string.

KeyedString Built-in Type

Built-in type consisting of a string payload and a second string that is the

key.

Octets Built-in Type

Built-in type consisting of a v ariable-le ngth array of opaque bytes.

KeyedOctets Built-in Type

Built-in type consisting of a variable-length array of opaque bytes and a string

that is the key.

5.10.1 Detailed Description

<<eXtension>> ( p. 199) RTI Connext provides a set of very simple data

types for you to use with the topics in your application.

The middleware provides four built-in types:

String: A payload consisting of a single string of characters. This type

has no key.

DDS KeyedString (p. 768): A payload consisting of a single string of

characters and a second string, the key, that identiﬁes the instance to

which the sample belongs.

DDS Octets (p. 799): A payload consisting of an opaque variable-length

array of bytes. This type has no key.

DDS KeyedOctets (p. 765): A payload consisting of an opaque variable-

length array of bytes and a string, the key, that identiﬁes the instance to

which the sample belongs.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.10 Built-in Types 73

The String and DDS KeyedString (p. 768) types are appropriate for simple

text-based applications. The DDS Octets (p. 799) and DDS KeyedOctets

(p. 765) types are appropriate for applications that perform their own custom

data serialization, s uch as legacy applications still in the process of migrating

to RTI Connext. In most cases, string-based or structured data is preferable to

opaque data, because the latter cannot be easily visualized in tools or used with

content-based ﬁlters (see DDSContentFilteredTopic (p. 1081)).

The built-in types are very simple in order to get you up and running as quickly

as possible. If you need a structured data type you can deﬁne your own type

with exactly the ﬁelds you need in one of two ways:

At compile time, by generating code from an IDL or XML ﬁle using the

rtiddsgen (p. 220) utility

At runtime, by using the Dynamic Data (p. 77) API

5.10.2 Managing Memory for Builtin Types

When a sample is written, the DataWriter serializes it and stores the result in

a buﬀer obtained from a pool of preallo cate d buﬀers. In the same way, when

a sample is received, the DataReader deserializes it and stores the result in a

sample coming from a pool of preallocated samples.

For builtin types, the maximum size of the buﬀers/samples and depends on the

nature of the application using the builtin type.

You can conﬁgure the maximum size of the builtin types on a per-DataWriter

and per-DataReader basis using the DDS PropertyQosPolicy (p. 834) in

DataWriters, DataReaders or Participants.

The following table lists the supported builtin type properties to conﬁgure mem-

ory allocation. When the properties are deﬁned in the DomainParticipant, they

are applicable to all DataWriters and DataReaders belonging to the Domain-

Participant unless they are overwrittem in the DataWriters and DataReaders.

The previous properties must be set consistently with respect to the correspond-

ing ∗.max size properties that set the maximum size of the builtin types in the

typecode.

5.10.3 Typecodes for Builtin Types

The typecodes associated with the builtin types are generated from the following

IDL type deﬁnitions:

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

74 Module Documentation

module DDS {

struct String {

string value;

};

struct KeyedString {

string key;

string value;

};

struct Octets {

sequence<octet> value;

};

struct KeyedOctets {

string key;

sequence<octet> value;

};

The maximum size of the strings and sequences that will be included in the type

code deﬁnitions can be conﬁgured on a per-DomainParticipant-basis by using

the properties in following table.

For more information about the built-in types, including how to control mem-

ory usage and maximum lengths, please see chapter 3, Data Types and Data

Samples, in the User’s Manual.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.10 Built-in Types 75

Property Description

dds.builtin type.string.alloc size Maximum size of the strings

published by the

DDSStringDataWriter (p. 1383)

or received the

DDSStringDataReader (p. 1379)

(includes the NULL-terminated

character).

Default:

dds.builtin type.string.max size if

deﬁned. Otherwise, 1024.

dds.builtin type.keyed string.alloc -

key size

Maximum size of the keys used by

the

DDSKeyedStringDataWriter

(p. 1304) or

DDSKeyedStringDataReader

(p. 1293) (includes the

NULL-terminated character).

Default: dds.builtin type.keyed -

string.max key size if deﬁned.

Otherwise, 1024.

dds.builtin type.keyed string.alloc -

size

Maximum size of the strings

published by the

DDSKeyedStringDataWriter

(p. 1304) or received by the

DDSKeyedStringDataReader

(p. 1293) (includes the

NULL-terminated character).

Default: dds.builtin type.keyed -

string.max size if deﬁned.

Otherwise, 1024.

dds.builtin type.octets.alloc size Maximum size of the octet

sequences published the

DDSOctetsDataWriter (p. 1331)

or received by the

DDSOctetsDataReader

(p. 1326).

Default:

dds.builtin type.octets.max size if

deﬁned. Otherwise, 2048.

dds.builtin type.keyed octets.alloc -

key size

Maximum size of the key published

by the

DDSKeyedOctetsDataWriter

(p. 1276) or received by the

DDSKeyedOctetsDataReader

(p. 1265) (includes the

NULL-terminated character).

Default: dds.builtin type.keyed -

octets.max key size if deﬁned.

Otherwise, 1024.

dds.builtin type.keyed octets.alloc -

size

Maximum size of the octets

sequences published by a

DDSKeyedOctetsDataWriter

(p. 1276) or received by a

DDSKeyedOctetsDataReader

(p. 1265).

Default: dds.builtin type.keyed -

octets.max size if deﬁned.

Otherwise, 2048.

Table 5.3: Builtin Types Allocation Properties

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

76 Module Documentation

Property Description

dds.builtin type.string.max size Maximum size of the strings

published by the StringDataWriters

and rec eived by the

StringDataReaders belonging to a

DomainParticipant (includes the

NULL-terminated character).

Default: 1024.

dds.builtin type.keyed string.max -

key size

Maximum size of the keys used by

the KeyedStringDataWriters and

KeyedStringDataReaders belonging

to a DomainParticipant (includes

the NULL-terminated character).

Default: 1024.

dds.builtin type.keyed string.max -

size

Maximum size of the strings

published by the

KeyedStringDataWriters and

received by the

KeyedStringDataReaders belonging

to a DomainParticipant using the

builtin type (includes the

NULL-terminated character).

Default: 1024

dds.builtin type.octets.max size Maximum size of the octet

sequences published by the

OctetsDataWriters and received by

the OctetsDataReader belonging to

a DomainParticipant.

Default: 2048

dds.builtin type.keyed octets.max -

key size

Maximum size of the keys used by

the KeyedOctetsStringDataWriters

and Ke yedOctetsStringDataReaders

belonging to a DomainParticipant

(includes the NULL-terminated

character).

Default: 1024.

dds.builtin type.keyed octets.max -

size

Maximum size of the octet

sequences published by the

KeyedOctetsDataWriters and

received by the

KeyedOctetsDataReaders belonging

to a DomainParticipant.

Default: 2048

Table 5.4: Properties for Allocating Size of Builtin Types, per DomainPartici-

pant

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.11 Dynamic Data 77

5.11 Dynamic Data

<<eXtension>> ( p. 199) The Dynamic Data API provides a way to inter-

act with arbitrarily complex data types at runtime without the need for code

generation.

Classes

class DDSDynamicDataTypeSupport

A factory for registering a dynamically deﬁned type and creating DDS -

DynamicData ( p. 622) objects.

class DDSDynamicDataReader

Reads (subscribes to) objects of type DDS DynamicData ( p. 622).

class DDSDynamicDataWriter

Writes (publishes) objects of type DDS DynamicData ( p. 622).

struct DDS DynamicDataProperty t

A collection of attributes used to conﬁgure DDS DynamicData ( p. 622)

objects.

struct DDS DynamicDataTypeSerializationProperty t

Properties that govern how data of a certain type will be serialized on the

network.

struct DDS DynamicDataInfo

A descriptor for a DDS DynamicData ( p. 622) object.

struct DDS DynamicDataMemberInfo

A descriptor for a single member (i.e. ﬁeld) of dynamically deﬁned data type.

struct DDS DynamicData

A sample of any complex data type, which can be inspected and manipulated

reﬂectively.

struct DDS DynamicDataSeq

An ordered collection of DDS DynamicData ( p. 622) elements.

struct DDS DynamicDataTypeProperty t

A collection of attributes used to conﬁgure DDSDynamicDataTypeSup-

port ( p. 1246) objects.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

78 Module Documentation

Deﬁnes

#deﬁne DDS DYNAMIC DATA MEMBER ID -

UNSPECIFIED

A sentinel value that indicates that no member ID is needed in order to

perform some operation.

Typedefs

typedef DDS Long DDS DynamicDataMemberId

An integer that uniquely identiﬁes some member of a data type within that

type.

Variables

struct DDS DynamicDataProperty t DDS DYNAMIC DATA -

PROPERTY DEFAULT

Sentinel constant indicating default values for DDS -

DynamicDataProperty t ( p. 725).

struct DDS DynamicDataTypeProperty t DDS DYNAMIC -

DATA TYPE PROPERTY DEFAULT

Sentinel constant indicating default values for DDS -

DynamicDataTypeProperty t ( p. 728).

5.11.1 Detailed Description

<<eXtension>> ( p. 199) The Dynamic Data API provides a way to inter-

act with arbitrarily complex data types at runtime without the need for code

generation.

This API allows you to deﬁne new data types, modify existing data types, and

interact reﬂectively with samples. To use it, you will take the following steps:

1. Obtain a DDS TypeCode (p. 992) (see Type Code Support (p. 56))

that deﬁnes the type deﬁnition you want to use.

A DDS TypeCode (p. 992) includes a type’s kind (DDS TCKind (p. 66)),

name, and members (that is , ﬁelds). You can create your own DDS TypeCode

(p. 992) using the DDS TypeCodeFactory (p. 1022) class – see, for example,

the DDS TypeCodeFactory::create struct tc (p. 1027) method. Alterna-

tively, you can use a remote DDS TypeCode (p. 992) that you discovered

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.11 Dynamic Data 79

on the network (see Built-i n Topics (p. 42)) or one generated by rtiddsgen

(p. 220).

2. Wrap the DDS TypeCode (p. 992) in a DDSDynamicDataType-

Support (p. 1246) object.

See the constructor DDSDynamicDataTypeSup-

port::DDSDynamicDataTypeSupport (p. 1247). This object lets you

connect the type deﬁnition to a DDSDomainParticipant (p. 1139) and

manage data samples (of type DDS DynamicData (p. 622)).

3. Register the DDSDynamicDataTypeSupport (p. 1246) with one or

more domain participant s.

See DDSDynamicDataTypeSupport::register type (p. 1249). This action

associates the data type with a logical name that you can use to create topics.

(Starting with this step, working with a dynamically deﬁned data type is almost

exactly the same as working with a generated one.)

4. Create a DDSTopic (p. 1419) from the DDSDomainParticipant

(p. 1139).

Use the name under which you registered your data type – see DDSDomain-

Participant::create topic (p. 1175). This DDSTopic (p. 1419) is what you

will use to produce and consume data.

5. Create a DDSDynamicDataWriter (p. 1252) and/or DDSDynam-

icDataReader (p. 1245).

These objects will produce and/or consume data (of type DDS DynamicData

(p. 622)) on the DDSTopic (p. 1419). You can create these objects directly

from the DDSDomainParticipant (p. 1139) – see DDSDomainPartici-

pant::create datawriter (p. 1204) and DDSDomainParticipant::create -

datareader (p. 1208) – or by ﬁrst creating intermediate DDSPublisher

(p. 1346) and DDSSubscriber (p. 1390) objects – see DDSDomainPartic-

ipant::create publisher (p. 1169) and DDSDomainParticipant::create -

subscriber (p. 1172).

6. Write and/or read the data of interest.

7. Tear down the objects described above.

You should delete them in the reverse order in which you created them. Note

that unregistering your data type with the DDSDomainParticipant (p. 1139)

is optional; all types are automatically unregistered when the DDSDomain-

Participant (p. 1139) itself is deleted.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

80 Module Documentation

5.11.2 Deﬁne Documentation

5.11.2.1 #deﬁne DDS DYNAMIC DATA MEMBER ID -

UNSPECIFIED

A sentinel value that indicates that no member ID is needed in order to perform

some operation.

Most commonly, this constant will be used in ”get” operations to indicate that

a lookup should be performed based on a name, not on an ID.

See also:

DDS DynamicDataMemberId (p. 80)

5.11.3 Typedef Documentation

5.11.3.1 typedef DDS Long DDS DynamicDataMemberId

An integer that uniquely identiﬁes some member of a data type within that

type.

The range of a member ID is the range of an unsigned short integer, except for

the value 0, which is reserved.

See also:

DDS DYNAMIC DATA MEMBER ID UNSPECIFIED (p. 80)

5.11.4 Variable Documentation

5.11.4.1 struct DDS DynamicDataProperty t

DDS DYNAMIC DATA PROPERTY DEFAULT

Sentinel constant indicating default values for DDS -

DynamicDataProperty t (p. 725).

Pass this object instead of your own DDS DynamicDataProperty t (p. 725)

object to use the default property values:

DDS_DynamicData* sample = new DDS_DynamicData(

myTypeCode,

&DDS_DYNAMIC_DATA_PROPERTY_DEFAULT);

See also:

DDS DynamicDataProperty t (p. 725)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.11 Dynamic Data 81

5.11.4.2 struct DDS DynamicDataTypeProperty t

DDS DYNAMIC DATA TYPE PROPERTY DEFAULT

Sentinel constant indicating default values for DDS -

DynamicDataTypeProperty t (p. 728).

Pass this object instead of your own DDS DynamicDataTypeProperty t

(p. 728) object to use the default property values:

DDS_DynamicDataTypeSupport* support = new DDS_DynamicDataTypeSupport(

myTypeCode,

&DDS_DYNAMIC_DATA_TYPE_PROPERTY_DEFAULT);

See also:

DDS DynamicDataTypeProperty t (p. 728)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

82 Module Documentation

5.12 Publication Module

Contains the DDSFlowController (p. 1259), DDSPublisher (p. 1346), and

DDSDataWriter (p. 1113) classes as well as the DDSPublisherListener

(p. 1370) and DDSDataWriterListener (p. 1133) interfaces, and more gen-

erally, all that is needed on the publication side.

Modules

Publishers

DDSPublisher ( p. 1346) ent ity and associated elements

Data Writers

DDSDataWriter ( p. 1113) entity and associated elements

Flow Controllers

<<eXtension>> (p. 199) DDSFlowController ( p. 1259) and associated

elements

5.12.1 Detailed Description

Contains the DDSFlowController (p. 1259), DDSPublisher (p. 1346), and

DDSDataWriter (p. 1113) classes as well as the DDSPublisherListener

(p. 1370) and DDSDataWriterListener (p. 1133) interfaces, and more gen-

erally, all that is needed on the publication side.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.13 Publishers 83

5.13 Publishers

DDSPublisher (p. 1346) entity and associated elements

Classes

class DDSPublisherListener

<<inter face>> (p. 199) DDSListener ( p. 1318) for DDSPublisher

( p. 1346) status.

class DDSPublisherSeq

Declares IDL sequence < DDSPublisher ( p. 1346) > .

class DDSPublisher

<<inter face>> (p. 199) A publisher is the object responsible for the actual

dissemination of publications.

struct DDS PublisherQos

QoS policies supported by a DDSPublisher ( p. 1346) entity.

Variables

struct DDS DataWriterQos DDS DATAWRITER QOS -

DEFAULT

Special value for creating DDSDataWriter ( p. 1113) with default QoS.

struct DDS DataWriterQos DDS DATAWRITER QOS USE -

TOPIC QOS

Special value for creating DDSDataWriter ( p. 1113) with a combination

of the default DDS DataWriterQos ( p. 553) and the DDS TopicQos

( p. 965).

5.13.1 Detailed Description

DDSPublisher (p. 1346) entity and associated elements

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

84 Module Documentation

5.13.2 Variable Documentation

5.13.2.1 struct DDS DataWriterQos DDS DATAWRITER QOS -

DEFAULT

Special value for creating DDSDataWriter (p. 1113) with default QoS.

When used in DDSPublisher::create datawriter (p. 1355), this sp ec ial value

is used to indicate that the DDSDataWriter (p. 1113) should be created

with the default DDSDataWriter (p. 1113) QoS by means of the operation

get default datawriter qos and using the resulting QoS to create the DDS-

DataWriter (p. 1113).

When used in DDSPublisher::set default datawriter qos (p. 1351), this

special value is used to indicate that the default QoS should be reset back

to the initial value that would be used if the DDSPublisher::set default -

datawriter qos (p. 1351) operation had never been called.

When used in DDSDataWriter::set qos (p. 1126), this special value is used

to indicate that the QoS of the DDSDataWriter (p. 1113) should be changed

to match the current defualt QoS set in the DDSPublisher (p. 1346) that the

DDSDataWriter (p. 1113) belongs to.

Note: You cannot use this value to get the default QoS values for a DataWriter;

for this purpose, use DDSDomainParticipant::get default datawriter -

qos (p. 1150).

See also:

DDSPublisher::create datawriter (p. 1355)

DDSPublisher::set default datawriter qos (p. 1351)

DDSDataWriter::set qos (p. 1126)

Examples:

HelloWorld publisher.cxx.

5.13.2.2 struct DDS DataWriterQos DDS DATAWRITER QOS -

USE TOPIC QOS

Special value for creating DDSDataWriter (p. 1113) with a combination of

the default DDS DataWriterQos (p. 553) and the DDS TopicQos (p. 965).

The use of this value is equivalent to the application obtaining the default

DDS DataWriterQos (p. 553) and the DDS TopicQos (p. 965) (by means

of the operation DDSTopic::get qos (p. 1423)) and then combining these

two QoS using the operation DDSPublisher::copy from topi c qos (p. 1364)

whereby any policy that is set on the DDS TopicQos (p. 965) ”overrides” the

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.13 Publishers 85

corresponding policy on the default QoS. The resulting QoS is then applied to

the creation of the DDSDataWriter (p. 1113).

This value should only be used in DDSPublisher::create datawriter

(p. 1355).

See also:

DDSPublisher::create datawriter (p. 1355)

DDSPublisher::get default datawriter qos (p. 1350)

DDSTopic::get qos (p. 1423)

DDSPublisher::copy from topic qos (p. 1364)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

86 Module Documentation

5.14 Data Writers

DDSDataWriter (p. 1113) entity and associated elements

Classes

struct FooDataWriter

<<inter face>> (p. 199) <<generic>> (p. 199) User data type speciﬁc

data writer.

class DDSDataWriterListener

<<inter face>> (p. 199) DDSListener ( p. 1318) for writer status.

class DDSDataWriter

<<inter face>> (p. 199) Allows an application to set the value of the data

to be published under a giv en DDSTopic ( p. 1419).

struct DDS OﬀeredDeadlineMissedStatus

DDS OFFERED DEADLINE MISSED STATUS ( p. 323)

struct DDS LivelinessLostStatus

DDS LIVELINESS LOST STATUS ( p. 325)

struct DDS OﬀeredIncompatibleQosStatus

DDS OFFERED INCOMPATIBLE QOS STATUS ( p. 323)

struct DDS PublicationMatchedStatus

DDS PUBLICATION MATCHED STATUS ( p. 325)

struct DDS ReliableWriterCacheEventCount

<<eXtension>> (p. 199) The number of times the number of unacknowl-

edged samples in the cache of a reliable writer hit a certain well-deﬁned

threshold.

struct DDS ReliableWriterCacheChangedStatus

<<eXtension>> (p. 199) A summary of the state of a data writer’s cache

of unacknowledged samples written.

struct DDS ReliableReaderActivityChangedStatus

<<eXtension>> (p. 199) Describes the activity (i.e. are acknowledgements

forthcoming) of reliable readers matched to a reliable writer.

struct DDS DataWriterCacheStatus

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.14 Data Writers 87

<<eXtension>> (p. 199) The status of the writer’s cache.

struct DDS DataWriterProto colStat us

<<eXtension>> (p. 199) The status of a writer’s internal protocol related

metrics, like the number of samples pushed, pulled, ﬁltered; and status of

wire protocol traﬃc.

struct DDS DataWriterQos

QoS policies supported by a DDSDataWriter ( p. 1113) entity.

5.14.1 Detailed Description

DDSDataWriter (p. 1113) entity and associated elements

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

88 Module Documentation

5.15 Flow Controllers

<<eXtension>> ( p. 199) DDSFlowController (p. 1259) and associated el-

ements

Classes

class DDSFlowController

<<inter face>> (p. 199) A ﬂow controller is the object responsible for shap-

ing the network traﬃc by determining when attached asynchronous DDS-

DataWriter ( p. 1113) instances are allowed to write data.

struct DDS FlowControll erTokenBucketProperty t

DDSFlowController ( p. 1259) uses the popular token bucket approach for

open loop network ﬂow control. The ﬂow control characteristics are deter-

mined by the token bucket properties.

struct DDS FlowControll erProperty t

Determines the ﬂow control characteristics of the DDSFlowController

( p. 1259).

Enumerations

enum DDS FlowControll erSchedulingPolicy {

DDS RR FLOW CONTROLLER SCHED POLICY,

DDS EDF FLOW CONTROLLER SCHED POLICY,

DDS HPF FLOW CONTROLLER SCHED POLICY }

Kinds of ﬂow controller scheduling policy.

Variables

char ∗ DDS DEFAULT FLOW CONTROLLER NAME

[default] Special value of DDS PublishModeQosPolicy::ﬂow -

controller name ( p. 855) that refers to the built-in default ﬂow controller.

char ∗ DDS FIXED RATE FLOW CONTROLLER NAME

Special value of DDS PublishMod eQosPolicy::ﬂow controller name

( p. 855) that refers to the built-in ﬁxed-rate ﬂow controller.

char ∗ DDS ON DEMAND FLOW CONTROLLER NAME

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.15 Flow Controllers 89

Special value of DDS PublishMod eQosPolicy::ﬂow controller name

( p. 855) that refers to the built-in on-demand ﬂow controller.

5.15.1 Detailed Description

<<eXtension>> ( p. 199) DDSFlowController (p. 1259) and associated el-

ements

DDSFlowController (p. 1259) provides the network traﬃc shaping ca-

pability to asynchronous DDSDataWriter (p. 1113) instances. For use

cases and advantages of publishing asnychronously, please refer to DDS -

PublishModeQosPolicy (p. 853) of DDS DataWriterQos (p. 553).

See also:

DDS PublishModeQosPolicy (p. 853)

DDS DataWriterQos::publish mode (p. 558)

DDS AsynchronousPublisherQosPolicy (p. 466)

5.15.2 Enumeration Type Documentation

5.15.2.1 enum DDS FlowControllerSchedulingPolicy

Kinds of ﬂow controller scheduling policy.

Samples written by an asynchronous DDSDataWriter (p. 1113) are not sent

in the context of the FooDataWriter::write (p. 1484) call. Instead, the mid-

dleware puts the samples in a queue for future processing. The DDSFlow-

Controller (p. 1259) associated with each asynchronous DataWriter instance

determines when the samples are actually sent.

Each DDSFlowController (p. 1259) maintains a separate FIFO queue for

each unique destination (remote application). Samples written by asynchronous

DDSDataWriter (p. 1113) instances associated with the ﬂow controller, are

placed in the queues that correspond to the intended destinations of the sample.

When tokens become available, a ﬂow controller must decide which queue(s)

to grant tokens ﬁrst. This is determined by the ﬂow controller’s scheduling

policy. Once a queue has been granted tokens, it is serviced by the asynchronous

publishing thread. The queued up samples will be coalesced and sent to the

corresponding destination. The number of samples sent depends on the data

size and the number of tokens granted.

QoS:

DDS FlowControllerProperty t (p. 749)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

90 Module Documentation

Enumerator:

DDS RR FLOW CONTROLLER SCHED POLICY Indicates to

ﬂow control in a round-robin fashion.

Whenever tokens become available, the ﬂow controller distributes the

tokens uniformly across all of its (non-empty) destination queues.

No des tinations are prioritized. Instead, all destinations are treated

equally and are serviced in a round-robin fashion.

DDS EDF FLOW CONTROLLER SCHED POLICY Indicates

to ﬂow control in an earliest-deadline-ﬁrst fashion.

A sample’s deadline is determined by the time it was written plus

the latency budget of the DataWriter at the time of the write call

(as speciﬁed in the DDS LatencyBudgetQosPolicy (p. 771)). The

relative priority of a ﬂow controller’s destination queue is determined

by the earliest deadline across all samples it contains.

When tokens become available, the DDSFlowController (p. 1259)

distributes tokens to the destination queues in order of their deadline

priority. In other words, the queue containing the sample with the ear-

liest deadline is serviced ﬁrst. The number of tokens granted equals

the number of tokens required to send the ﬁrst sample in the queue.

Note that the priority of a queue may change as samples are sent (i.e.

removed from the queue). If a sample must be sent to multiple destina-

tions or two samples have an equal deadline value, the corresp onding

destination queues are serviced in a round-robin fashion.

Hence, under the default DDS -

LatencyBudgetQosPolicy::duration (p. 772) setting, an EDF -

FLOW CONTROLLER SCHED POLICY DDSFlowController (p. 1259)

preserves the order in which the user calls FooDataWriter::write

(p. 1484) across the DataWriters associated with the ﬂow controller.

Since the DDS LatencyBudgetQosPolicy (p. 771) is mutable, a

sample written second may contain an earlier deadline than the sam-

ple written ﬁrst if the DDS LatencyBudgetQosPolicy::duration

(p. 772) value is suﬃciently decreased in between writing the two sam-

ples. In that case, if the ﬁrst sample is not yet written (still in queue

waiting for its turn), it inherits the priority corresponding to the (ear-

lier) deadline from the second sample.

In other words, the priority of a destination queue is always determined

by the earliest deadline among all samples contained in the queue. This

priority inheritance approach is required in order to both honor the up-

dated DDS LatencyBudgetQosPolicy::duration (p. 772) and ad-

here to the DDSDataWriter (p. 1113) in-order data delivery guar-

antee.

[default] for DDSDataWriter (p. 1113)

DDS HPF FLOW CONTROLLER SCHED POLICY Indicates

/o ﬂow control in an highest-priority-ﬁrst fashion.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.15 Flow Controllers 91

Determines the next destination queue to service as determined by

the publication priority of the DDSDataWriter (p. 1113), channel of

multi-channel DataWriter, or individual sample.

The relative priority of a ﬂow controller’s destination queue is deter-

mined by the highest publication priority of all samples it contains.

When tokens become available, the DDSFlowController (p. 1259)

distributes tokens to the destination queues in order of their publica-

tion priority. In other words, the queue containing the sample with

the highest publication priority is serviced ﬁrst. The number of tokens

grante d equals the number of tokens required to send the ﬁrst sample

in the queue. Note that the priority of a queue may change as samples

are sent (i.e. removed from the queue). If a sample must be sent to

multiple destinations or two samples have an equal publication prior-

ity, the corresponding destination queues are serviced in a round-robin

fashion.

This priority inheritance approach is required in order to both

honor the des ignated publication priority and adhere to the DDS-

DataWriter (p. 1113) in-order data delivery guarantee.

5.15.3 Variable Documentation

5.15.3.1 char∗ DDS DEFAULT FLOW CONTROLLER NAME

[default] Special value of DDS PublishModeQosPolicy:: ﬂow controller -

name (p. 855) that refers to the built-in default ﬂow controller.

RTI Connext provides several built-in DDSFlowController (p. 1259) for use

with an asynchronous DDSDataWriter (p. 1113). The user can choose to use

the built-in ﬂow controllers and optionally modify their properties or can create

a custom ﬂow controller.

By default, ﬂow control is disabled. That is, the built-in DDS DEFAULT -

FLOW CONTROLLER NAME (p. 91) ﬂow controller does not apply any

ﬂow control. Instead, it allows data to be sent asynchronously as soon as it is

written by the DDSDataWriter (p. 1113).

Essentially, this is equivalent to a user-created DDSFlowController (p. 1259)

with the following DDS FlowControllerProperty t (p. 749) s ettings:

- DDS FlowControllerProperty t::scheduling policy (p. 750) = DDS -

EDF FLOW CONTROLLER SCHED POLICY (p. 90)

- DDS FlowControllerProperty t::token bucket (p. 750) max tokens =

DDS LENGTH UNLIMITED (p. 371)

- DDS FlowControllerProperty t::token bucket (p. 750) tokens added -

per period = DDS LENGTH UNLIMITED (p. 371)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

92 Module Documentation

- DDS FlowControllerProperty t::token bucket (p. 750) tokens -

leaked per period = 0

- DDS FlowControllerProperty t::token bucket (p. 750) period = 1 sec-

ond

- DDS FlowControllerProperty t::token bucket (p. 750) bytes per -

token = DDS LENGTH UNLIMITED (p. 371)

See also:

DDSPublisher::create datawriter (p. 1355)

DDSDomainParticipant::lookup ﬂowcontroller (p. 1186)

DDSFlowController::set property (p. 1260)

DDS PublishModeQosPolicy (p. 853)

DDS AsynchronousPublisherQosPolicy (p. 466)

5.15.3.2 char∗ DDS FIXED RATE FLOW CONTROLLER NAME

Special value of DDS PublishModeQosPolicy::ﬂow controller name

(p. 855) that refers to the built-in ﬁxed-rate ﬂow controller.

RTI Connext provides several builtin DDSFlowController (p. 1259) for use

with an asynchronous DDSDataWriter (p. 1113). The user can choose to use

the built-in ﬂow controllers and optionally modify their properties or can create

a custom ﬂow controller.

The built-in DDS FIXED RATE FLOW CONTROLLER NAME

(p. 92) ﬂow controller shapes the network traﬃc by allowing data to be sent

only once every second. Any accumulated samples destined for the same

destination are coalesced into as few network packets as possible.

Essentially, this is equivalent to a user-created DDSFlowController (p. 1259)

with the following DDS FlowControllerProperty t (p. 749) settings:

- DDS FlowControllerProperty t::scheduling policy (p. 750) = DDS -

EDF FLOW CONTROLLER SCHED POLICY (p. 90)

- DDS FlowControllerProperty t::token bucket (p. 750) max tokens =

DDS LENGTH UNLIMITED (p. 371)

- DDS FlowControllerProperty t::token bucket (p. 750) tokens added -

per period = DDS LENGTH UNLIMITED (p. 371)

- DDS FlowControllerProperty t::token bucket (p. 750) tokens -

leaked per period = DDS LENGTH UNLIMITED (p. 371)

- DDS FlowControllerProperty t::token bucket (p. 750) period = 1 sec-

ond

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.15 Flow Controllers 93

- DDS FlowControllerProperty t::token bucket (p. 750) bytes per -

token = DDS LENGTH UNLIMITED (p. 371)

See also:

DDSPublisher::create datawriter (p. 1355)

DDSDomainParticipant::lookup ﬂowcontroller (p. 1186)

DDSFlowController::set property (p. 1260)

DDS PublishModeQosPolicy (p. 853)

DDS AsynchronousPublisherQosPolicy (p. 466)

5.15.3.3 char∗ DDS ON DEMAND FLOW CONTROLLER -

NAME

Special value of DDS PublishModeQosPolicy::ﬂow controller name

(p. 855) that refers to the built-in on-demand ﬂow controller.

RTI Connext provides several builtin DDSFlowController (p. 1259) for use

with an asynchronous DDSDataWriter (p. 1113). The user can choose to use

the built-in ﬂow controllers and optionally modify their properties or can create

a custom ﬂow controller.

The built-in DDS ON DEMAND FLOW CONTROLLER NAME

(p. 93) allows data to be sent only when the user calls DDSFlowCon-

troller::trigger ﬂow (p. 1261). With each trigger, all accumulated data

since the previous trigger is sent (across all DDSPublisher (p. 1346) or

DDSDataWriter (p. 1113) instances). In other words, the network traﬃc

shape is fully controlled by the user. Any accumulated samples destined for

the same destination are coalesced into as few network packets as possible.

This external trigger source is ideal for users who want to implement some form

of closed-loop ﬂow control or who want to only put data on the wire every so

many samples (e.g. with the number of samples based on NDDS Transport -

Property t::gather send buﬀer count max (p. 1525)).

Essentially, this is equivalent to a user-created DDSFlowController (p. 1259)

with the following DDS FlowControllerProperty t (p. 749) s ettings:

- DDS FlowControllerProperty t::scheduling policy (p. 750) = DDS -

EDF FLOW CONTROLLER SCHED POLICY (p. 90)

- DDS FlowControllerProperty t::token bucket (p. 750) max tokens =

DDS LENGTH UNLIMITED (p. 371)

- DDS FlowControllerProperty t::token bucket (p. 750) tokens added -

per period = DDS LENGTH UNLIMITED (p. 371)

- DDS FlowControllerProperty t::token bucket (p. 750) tokens -

leaked per period = DDS LENGTH UNLIMITED (p. 371)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

94 Module Documentation

- DDS FlowControllerProperty t::token bucket (p. 750) period =

DDS DURATION INFINITE (p. 305)

- DDS FlowControllerProperty t::token bucket (p. 750) bytes per -

token = DDS LENGTH UNLIMITED (p. 371)

See also:

DDSPublisher::create datawriter (p. 1355)

DDSDomainParticipant::lookup ﬂowcontroller (p. 1186)

DDSFlowController::trigger ﬂow (p. 1261)

DDSFlowController::set property (p. 1260)

DDS PublishModeQosPolicy (p. 853)

DDS AsynchronousPublisherQosPolicy (p. 466)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.16 Subscription Module 95

5.16 Subscription Module

Contains the DDSSubscriber (p. 1390), DDSDataReader (p. 1087),

DDSReadCondition (p. 1374), and DDSQueryCondition (p. 1372) classes,

as well as the DDSSubscriberListener (p. 1414) and DDSDataReaderLis-

tener (p. 1108) interfaces, and more generally, all that is needed on the s ub-

scription s ide.

Modules

Subscribers

DDSSubscriber ( p. 1390) en tity and associated elements

DataReaders

DDSDataReader ( p. 1087) entity and associated elements

Data Samples

DDS SampleInfo ( p. 912), DDS SampleStateKind ( p. 111), DDS -

ViewStateKind ( p. 113), DDS InstanceStateKind ( p. 116) and associ-

ated elements

5.16.1 Detailed Description

Contains the DDSSubscriber (p. 1390), DDSDataReader (p. 1087),

DDSReadCondition (p. 1374), and DDSQueryCondition (p. 1372) classes,

as well as the DDSSubscriberListener (p. 1414) and DDSDataReaderLis-

tener (p. 1108) interfaces, and more generally, all that is needed on the s ub-

scription s ide.

5.16.2 Access to data samples

Data is made available to the application by the following operations on

DDSDataReader (p. 1087) objects: FooDataReader::read (p. 1447),

FooDataReader::read w condition (p. 1454), FooDataReader::take

(p. 1448), FooDataReader::take w condition (p. 1456), and the other

variants of read() and take().

The general s emantics of the read() operation is that the application only gets

access to the corresponding data (i.e. a precise instance value); the data remains

the responsibility of RTI Connext and can be read again.

The semantics of the take() operations is that the application takes full re-

sponsibility for the data; that data will no longer be available locally to RTI

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

96 Module Documentation

Connext. Consequently, it is possible to access the same information multiple

times only if all previous accesses were read() operations, not take().

Each of these operations returns a collection of Data values and associated

DDS SampleInfo (p. 912) objects. Each data value represents an atom of data

information (i.e., a value for one instance). This collection may contain samples

related to the same or diﬀerent instances (identiﬁed by the key). Multiple

samples can refer to the same instance if the settings of the HISTORY (p. 367)

QoS allow for it.

To return the memory back to the middleware, every read() or take()

that retrieves a sequence of samples must be followed with a call to

FooDataReader::return loan (p. 1471).

See also:

Interpretation of the SampleInfo (p. 913)

5.16.2.1 Data access patterns

The application accesses data by means of the operations read or take on the

DDSDataReader (p. 1087). These operations return an ordered collection of

DataSamples consisting of a DDS SampleInfo (p. 912) part and a Data part.

The way RTI Connext builds the collection depends on QoS policies set on

the DDSDataReader (p. 1087) and DDSSubscriber (p. 1390), as well as the

source timestamp of the samples, and the parameters passe d to the read() /

take() operations, namely:

the desired sample states (any combination of DDS SampleStateKind

(p. 111))

the desired view states (any combination of DDS ViewStateKind

(p. 113))

the desired instance states (any combination of DDS -

InstanceStateKind (p. 116))

The read() and take() operations are non-blocking and just deliver what is

currently available that matches the speciﬁed states.

The read w condition() and take w condition() operations take a

DDSReadCondition (p.

1374) object as a parameter instead of sample, view

or instance states. The behaviour is that the samples returned will only be

those for which the condition is DDS BOOLEAN TRUE (p. 298). These

operations, in conjunction with DDSReadCondition (p. 1374) objects and a

DDSWaitSet (p. 1433), allow performing waiting reads.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.16 Subscription Module 97

Once the data samples are available to the data readers, they can be read or

taken by the application. The basic rule is that the application may do this in

any order it wishes. This approach is very ﬂexible and allows the application

ultimate control.

To acce ss data coherently, or in order, the PRESENTATION (p.

351) QoS

must be set properly.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

98 Module Documentation

5.17 Subscribers

DDSSubscriber (p. 1390) entity and associated elements

Classes

class DDSSubscriberListener

<<inter face>> (p. 199) DDSListener ( p. 1318) for status about a sub-

scriber.

class DDSSubscriberSeq

Declares IDL sequence < DDSSubscriber ( p. 1390) > .

class DDSSubscriber

<<inter face>> (p. 199) A subscriber is the object responsible for actually

receiving data from a subscription.

struct DDS SubscriberQos

QoS policies supported by a DDSSubscriber ( p. 1390) entity.

Variables

struct DDS DataReaderQos DDS DATAREADER QOS -

DEFAULT

Special value for creating data reader with default QoS.

struct DDS DataReaderQos DDS DATAREADER QOS USE -

TOPIC QOS

Special value for creating DDSDataReader ( p. 1087) with a combination

of the default DDS DataReaderQos ( p. 515) and the DDS TopicQos

( p. 965).

5.17.1 Detailed Description

DDSSubscriber (p. 1390) entity and associated elements

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.17 Subscribers 99

5.17.2 Variable Documentation

5.17.2.1 struct DDS DataReaderQos DDS DATAREADER QOS -

DEFAULT

Special value for creating data reader with default QoS.

When used in DDSSubscriber::create datareader (p. 1399), this special

value is used to indicate that the DDSDataReader (p. 1087) should be created

with the default DDSDataReader (p. 1087) QoS by means of the operation

get default datareader qos and using the resulting QoS to create the DDS-

DataReader (p. 1087).

When used in DDSSubscriber::set default datareader qos (p. 1395), this

special value is used to indicate that the default QoS should be reset back

to the initial value that would be used if the DDSSubscriber::set defaul t -

datareader qos (p. 1395) operation had never been called.

When used in DDSDataReader::set qos (p. 1102), this special value is used

to indicate that the QoS of the DDSDataReader (p. 1087) should be changed

to match the current default QoS set in the DDSSubscriber (p. 1390) that the

DDSDataReader (p. 1087) belongs to.

Note: You cannot use this value to get the default QoS values for a DataReader;

for this purp ose , use DDSDomainParticipant::get default datareader -

qos (p. 1152).

See also:

DDSSubscriber::create datareader (p. 1399)

DDSSubscriber::set default datareader qos (p. 1395)

DDSDataReader::set qos (p. 1102)

Examples:

HelloWorld subscriber.cxx.

5.17.2.2 struct DDS DataReaderQos DDS DATAREADER QOS -

USE TOPIC QOS

Special value for creating DDSDataReader (p. 1087) with a combination of

the default DDS DataReaderQos (p. 515) and the DDS TopicQos (p. 965).

The use of this value is equivalent to the application obtaining the default

DDS DataReaderQos (p. 515) and the DDS TopicQos (p. 965) (by means

of the operation DDSTopic::get qos (p. 1423)) and then combining these two

QoS using the ope ration DDSSubscriber::copy from topic qos (p. 1409)

whereby any policy that is set on the DDS TopicQos (p. 965) ”overrides”

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

100 Module Documentation

the corresponding policy on the default QoS. The resulting QoS is then applied

to the creation of the DDSDataReader (p. 1087).

This value should only be used in DDSSubscriber::create datareader

(p. 1399).

See also:

DDSSubscriber::create datareader (p. 1399)

DDSSubscriber::get default datareader qos (p. 1394)

DDSTopic::get qos (p. 1423)

DDSSubscriber::copy from topic qos (p. 1409)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.18 DataReaders 101

5.18 DataReaders

DDSDataReader (p. 1087) entity and associated elements

Modules

Read Conditions

DDSReadCondition ( p. 1374) and associated elements

Query Conditions

DDSQueryCondition ( p. 1372) and associated elements

Classes

struct FooDataReader

<<inter face>> (p. 199) <<generic>> (p. 199) User data type-speciﬁc

data reader.

class DDSDataReaderSeq

Declares IDL sequence < DDSDataReader ( p. 1087) > .

class DDSDataReaderListener

<<inter face>> (p. 199) DDSListener ( p. 1318) for reader status.

class DDSDataReader

<<inter face>> (p. 199) Allows the application to: (1) declare the data it

wishes to receive (i.e. make a subscription) and (2) access the data received

by the attached DDSSubscriber ( p. 1390).

struct DDS RequestedDeadlineMissedStatus

DDS REQUESTED DEADLINE MISSED STATUS ( p. 323)

struct DDS LivelinessChangedStatus

DDS LIVELINESS CHANGED STATUS ( p. 325)

struct DDS RequestedIncompatibleQosStatus

DDS REQUESTED INCOMPATIBLE QOS STATUS ( p. 323)

struct DDS SampleLostStatus

DDS SAMPLE LOST STATUS ( p. 324)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

102 Module Documentation

struct DDS SampleRejectedStatus

DDS SAMPLE REJECTED STATUS ( p. 324)

struct DDS SubscriptionMatchedStatus

DDS SUBSCRIPTION MATCHED STATUS ( p. 326)

struct DDS DataReaderCacheStatus

<<eXtension>> (p. 199) The status of the reader’s cache.

struct DDS DataReaderProtocolStatus

<<eXtension>> (p. 199) The status of a reader’s internal protocol related

metrics, like the number of samples received, ﬁltered, re jected; and status of

wire protocol traﬃc.

struct DDS DataReaderQos

QoS policies supported by a DDSDataReader ( p. 1087) entity.

Enumerations

enum DDS SampleLostStatusKind {

DDS NOT LOST,

DDS LOST BY WRITER,

DDS LOST BY INSTANCES LIMIT,

DDS LOST BY REMOTE WRITERS PER INSTANCE -

LIMIT,

DDS LOST BY INCOMPLETE COHERENT SET,

DDS LOST BY LARGE COHERENT SET,

DDS LOST BY SAMPLES PER REMOTE WRITER LIMIT,

DDS LOST BY VIRTUAL WRITERS LIMIT,

DDS LOST BY REMOTE WRITERS PER SAMPLE LIMIT,

DDS LOST BY AVAILABILITY WAITING TIME,

DDS LOST BY REMOTE WRITER SAMPLES PER -

VIRTUAL QUEUE LIMIT,

DDS LOST BY OUT OF MEMORY }

Kinds of reasons why a sample was lost.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.18 DataReaders 103

enum DDS SampleRejectedStatusKind {

DDS NOT REJECTED,

DDS REJECTED BY INSTANCES LIMIT,

DDS REJECTED BY SAMPLES LIMIT,

DDS REJECTED BY SAMPLES PER INSTANCE LIMIT,

DDS REJECTED BY REMOTE WRITERS LIMIT,

DDS REJECTED BY REMOTE WRITERS PER -

INSTANCE LIMIT,

DDS REJECTED BY SAMPLES PER REMOTE WRITER -

LIMIT,

DDS REJECTED BY VIRTUAL WRITERS LIMIT,

DDS REJECTED BY REMOTE WRITERS PER SAMPLE -

LIMIT,

DDS REJECTED BY REMOTE WRITER SAMPLES PER -

VIRTUAL QUEUE LIMIT }

Kinds of reasons for rejecting a sample.

5.18.1 Detailed Description

DDSDataReader (p. 1087) entity and associated elements

5.18.2 Enumeration Type Documentation

5.18.2.1 enum DDS SampleLostStatusKind

Kinds of reasons why a sample was lost.

Enumerator:

DDS NOT LOST The sample was not lost.

See also:

ResourceLimitsQosPolicy

DDS LOST BY WRITER A DataWriter removed the sample before

being received by the DDSDataReader (p. 1087).

This constant is an extension to the DDS standard.

DDS LOST BY INSTANCES LIMIT A resource limit on the num-

ber of instances was reached.

This constant is an extension to the DDS standard.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

104 Module Documentation

See also:

ResourceLimitsQosPolicy

DDS LOST BY REMOTE WRITERS PER INSTANCE LIMIT

A resource limit on the number of remote writers for a single instance

from which a DDSDataReader (p. 1087) may read was reached.

This constant is an extension to the DDS standard.

See also:

DDS DataReaderResourceLimitsQosPolicy (p. 521)

DDS LOST BY INCOMPLETE COHERENT SET A sample is

lost because it is part of an incomplete coherent set.

This constant is an extension to the DDS standard.

DDS LOST BY LARGE COHERENT SET A sample is lost be-

cause it is part of a large coherent set.

This constant is an extension to the DDS standard.

DDS LOST BY SAMPLES PER REMOTE WRITER LIMIT

A resource limit on the number of samples from a given remote writer

that a DDSDataReader (p. 1087) may store was reached.

This constant is an extension to the DDS standard.

See also:

DDS DataReaderResourceLimitsQosPolicy (p. 521)

DDS LOST BY VIRTUAL WRITERS LIMIT A resource limit

on the number of virtual writers from which a DDSDataReader

(p. 1087) may read was reached.

This constant is an extension to the DDS standard.

See also:

DDS DataReaderResourceLimitsQosPolicy (p. 521)

DDS LOST BY REMOTE WRITERS PER SAMPLE LIMIT

A resource limit on the number of remote writers per sample was

reached.

This constant is an extension to the DDS standard.

See also:

DDS DataReaderResourceLimitsQosPolicy (p. 521)

DDS LOST BY AVAILABILITY WAITING TIME DDS -

AvailabilityQosPolicy::max data availability waiting time

(p. 473) expired.

This constant is an extension to the DDS standard.

See also:

DDS DataReaderResourceLimitsQosPolicy (p. 521)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.18 DataReaders 105

DDS LOST BY REMOTE WRITER SAMPLES PER VIRTUAL QUEUE LIMIT

A resource limit on the number of samples published by a remote

writer on behalf of a virtual writer that a DDSDataReader (p. 1087)

may store was reached.

This constant is an extension to the DDS standard.

See also:

DDS DataReaderResourceLimitsQosPolicy (p. 521)

DDS LOST BY OUT OF MEMORY A sample was lost because

there was not enough memory to store the sample.

This constant is an extension to the DDS standard.

See also:

DDS DataReaderResourceLimitsQosPolicy (p. 521)

5.18.2.2 enum DDS SampleRejectedStatusKind

Kinds of reasons for rejecting a sample.

Enumerator:

DDS NOT REJECTED Samples are never rejected.

See also:

DDS DataReaderResourceLimitsQosPolicy (p. 521)

DDS REJECTED BY INSTANCES LIMIT A resource limit on

the number of instances was reached.

See also:

DDS DataReaderResourceLimitsQosPolicy (p. 521)

DDS REJECTED BY SAMPLES LIMIT A resource limit on the

number of samples was reached.

See also:

DDS DataReaderResourceLimitsQosPolicy (p. 521)

DDS REJECTED BY SAMPLES PER INSTANCE LIMIT A

resource limit on the number of samples per instance was reached.

See also:

ResourceLimitsQosPolicy

DDS REJECTED BY REMOTE WRITERS LIMIT A resource

limit on the number of remote writers from which a DDSDataReader

(p. 1087) may read was reached.

This constant is an extension to the DDS standard.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

106 Module Documentation

See also:

DDS DataReaderResourceLimitsQosPolicy (p. 521)

DDS REJECTED BY REMOTE WRITERS PER INSTANCE LIMIT

A resource limit on the number of remote writers for a single instance

from which a DDSDataReader (p. 1087) may read was reached.

This constant is an extension to the DDS standard.

See also:

DDS DataReaderResourceLimitsQosPolicy (p. 521)

DDS REJECTED BY SAMPLES PER REMOTE WRITER LIMIT

A resource limit on the number of samples from a given remote writer

that a DDSDataReader (p. 1087) may store was reached.

This constant is an extension to the DDS standard.

See also:

DDS DataReaderResourceLimitsQosPolicy (p. 521)

DDS REJECTED BY VIRTUAL WRITERS LIMIT A resource

limit on the number of virtual writers from which a DDSDataReader

(p. 1087) may read was reached.

This constant is an extension to the DDS standard.

See also:

DDS DataReaderResourceLimitsQosPolicy (p. 521)

DDS REJECTED BY REMOTE WRITERS PER SAMPLE LIMIT

A resource limit on the number of remote writers per sample was

reached.

This constant is an extension to the DDS standard.

See also:

DDS DataReaderResourceLimitsQosPolicy (p. 521)

DDS REJECTED BY REMOTE WRITER SAMPLES PER VIRTUAL QUEUE LIMIT

A resource limit on the number of samples published by a remote

writer on behalf of a virtual writer that a DDSDataReader (p. 1087)

may store was reached.

This constant is an extension to the DDS standard.

See also:

DDS DataReaderResourceLimitsQosPolicy (p. 521)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.19 Read Conditions 107

5.19 Read Conditions

DDSReadCondition (p. 1374) and associated elements

Classes

class DDSReadCondition

<<inter face>> (p. 199) Conditions speciﬁcally dedicated to read operations

and attached to one DDSDataReader ( p. 1087).

5.19.1 Detailed Description

DDSReadCondition (p. 1374) and associated elements

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

108 Module Documentation

5.20 Query Conditions

DDSQueryCondition (p. 1372) and associated elements

Classes

class DDSQueryCondition

<<inter face>> (p. 199) These are specialised DDSReadCondition

( p. 1374) objects that allow the application to also specify a ﬁlter on the

locally available data.

5.20.1 Detailed Description

DDSQueryCondition (p. 1372) and associated elements

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.21 Data Samples 109

5.21 Data Samples

DDS SampleInfo (p. 912), DDS Sample StateKi nd (p. 111), DDS -

ViewStateKind (p. 113), DDS InstanceStateKind (p. 116) and associated

elements

Modules

Sample States

DDS SampleStateKind ( p. 111) and associated elements

View States

DDS ViewStateKind ( p. 113) and associated elements

Instance States

DDS InstanceStateKind ( p. 116) and associated elements

Classes

struct DDS SampleInfo

Information that accompanies each sample that is read or taken.

struct DDS SampleInfoSeq

Declares IDL sequence < DDS SampleInfo ( p. 912) > .

Functions

void DDS SampleInfo get sample identity (const struct DDS -

SampleInfo ∗self, struct DDS SampleIdentity t ∗identity)

<<eXtension>> (p. 199) Retrieves the identity of the sample

void DDS SampleInfo get related sample identity (const struct

DDS SampleInfo ∗self, struct DDS SampleIdentity t ∗related -

identity)

<<eXtension>> (p. 199) Retrieves the identity of a sample related to this

one

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

110 Module Documentation

5.21.1 Detailed Description

DDS SampleInfo (p. 912), DDS SampleSt ateKi nd (p. 111), DDS -

ViewStateKind (p. 113), DDS InstanceStateKind (p. 116) and associated

elements

5.21.2 Function Documentation

5.21.2.1 void DDS SampleInfo get sample identity (const struct

DDS SampleInfo ∗ self, struct DDS SampleIdentity t ∗

identity)

<<eXtension>> ( p. 199) Retrieves the identity of the sample

The identity is comp osed of the DDS SampleInfo::original publication -

virtual guid (p. 920) and the DDS SampleInfo::original publication -

virtual sequence number (p. 920)

See also:

DDS SampleInfo get related sample identity (p. 110)

5.21.2.2 void DDS SampleInfo get related sample identity

(const struct DDS SampleInfo ∗ self, struct

DDS SampleIdentity t ∗ related identity)

<<eXtension>> ( p. 199) Retrieves the identity of a sample related to this

one

A sample can be logically related to another sample, when the DDS-

DataWriter (p. 1113) wrote it using DDS WriteParams t::related -

sample identity (p. 1068). By default, a sample does not have a related sam-

ple, and this operation returns DDS UNKNOWN SAMPLE IDENTITY

(p. 449).

The related identity is com posed of the DDS

SampleInfo::related original -

publication virtual guid (p. 921) and the DDS SampleInfo::related -

original publication virtual sequence number (p. 921)

See also:

DDS WriteParams t::related sample identity (p. 1068)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.22 Sample States 111

5.22 Sample States

DDS SampleStateKind (p. 111) and associated elements

Typedefs

typedef DDS UnsignedLong DDS SampleStateMask

A bit-mask (list) of sample states, i.e. DDS SampleStateKind ( p. 111).

Enumerations

enum DDS SampleStateKind {

DDS READ SAMPLE STATE = 0x0001 << 0,

DDS NOT READ SAMPLE STATE = 0x0001 << 1 }

Indicates whether or not a sample has ever been read.

Variables

const DDS SampleStateMask DDS ANY SAMPLE STATE

Any sample state DDS READ SAMPLE STATE ( p. 112) | DDS -

NOT READ SAMPLE STATE ( p. 112).

5.22.1 Detailed Description

DDS SampleStateKind (p. 111) and associated elements

5.22.2 Typedef Documentation

5.22.2.1 typedef DDS UnsignedLong DDS SampleStateMask

A bit-mask (list) of sample states, i.e. DDS SampleStateKind (p. 111).

5.22.3 Enumeration Type Documentation

5.22.3.1 enum DDS SampleStateKind

Indicates whether or not a sample has ever been read.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

112 Module Documentation

For each sample received, the middleware internally maintains a sample state

relative to each DDSDataReader (p. 1087). The sample state can be either:

DDS READ SAMPLE STATE (p. 112) indicates that the DDS-

DataReader (p. 1087) has already accessed that sample by means of a

read or take operation.

DDS NOT READ SAMPLE STATE (p. 112) indicates that the

DDSDataReader (p. 1087) has not accessed that sample before.

The sample state will, in general, b e diﬀerent for each sample in the collection

returned by read or take.

Enumerator:

DDS READ SAMPLE STATE Sample has been read.

DDS NOT READ SAMPLE STATE Sample has not been read.

5.22.4 Variable Documentation

5.22.4.1 const DDS SampleStateMask DDS ANY SAMPLE -

STATE

Any sample state DDS READ SAMPLE STATE (p. 112) | DDS NOT -

READ SAMPLE STATE (p. 112).

Examples:

HelloWorld subscriber.cxx.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.23 View States 113

5.23 View States

DDS ViewStateKind (p. 113) and associated elements

Typedefs

typedef DDS UnsignedLong DDS ViewStateMask

A bit-mask (list) of view states, i.e. DDS ViewStateKind ( p. 113).

Enumerations

enum DDS ViewStateKind {

DDS NEW VIEW STATE = 0x0001 << 0,

DDS NOT NEW VIEW STATE = 0x0001 << 1 }

Indicates whether or not an instance is new.

Variables

const DDS ViewStateMask DDS ANY VIEW STATE

Any view state DDS NEW VIEW STATE ( p. 114) | DDS NOT -

NEW VIEW STATE ( p. 114).

5.23.1 Detailed Description

DDS ViewStateKind (p. 113) and associated elements

5.23.2 Typedef Documentation

5.23.2.1 typedef DDS UnsignedLong DDS ViewStateMask

A bit-mask (list) of view states, i.e. DDS ViewStateKind (p. 113).

5.23.3 Enumeration Type Documentation

5.23.3.1 enum DDS ViewStateKind

Indicates whether or not an instance is new.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

114 Module Documentation

For each instance (identiﬁed by the key), the middleware internally maintains

a view state relative to each DDSDataReader (p. 1087). The view state can

be either:

DDS NEW VIEW STATE (p. 114) indicates that either this is the

ﬁrst time that the DDSDataReader (p. 1087) has ever accessed samples

of that instance, or else that the DDSDataReader (p. 1087) has accessed

previous samples of the instance, but the instance has since been reborn

(i.e. become not-alive and then alive again). These two cases are distin-

guished by examining the DDS SampleInfo::disposed generation -

count (p. 918) and the DDS SampleInfo::no writers generation -

count (p. 918).

DDS NOT NEW VIEW STATE (p. 114) indicates that the DDS-

DataReader (p. 1087) has already accessed samples of the same instance

and that the instance has not been reborn since.

The view state available in the DDS SampleInfo (p. 912) is a snapshot of the

view state of the instance relative to the DDSDataReader (p. 1087) used to

access the samples at the time the collection was obtained (i.e. at the time read

or take was called). The view state is therefore the same for all samples in the

returned collec tion that refer to the same instance.

Once an instance has been detected as not having any ”live” writers and all the

samples associated with the instance are ”taken” from the DDSDataReader

(p. 1087), the middleware can reclaim all local resources regarding the instance.

Future samples will be treated as ”never seen.”

Enumerator:

DDS NEW VIEW STATE New instance. This latest generation of

the instance has not previously been accessed.

DDS NOT NEW VIEW STATE Not a new instance. This latest

generation of the instance has previously been accessed.

5.23.4 Variable Documentation

5.23.4.1 const DDS ViewStateMask DDS ANY VIEW STATE

Any view state DDS NEW VIEW STATE (p. 114) | DDS NOT NEW -

VIEW STATE (p. 114).

Examples:

HelloWorld subscriber.cxx.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.24 Instance States 115

5.24 Instance States

DDS InstanceStateKind (p. 116) and associated elements

Typedefs

typedef DDS UnsignedLong DDS InstanceStateMask

A bit-mask (list) of instance states, i.e. DDS InstanceStateKind ( p. 116).

Enumerations

enum DDS InstanceStateKind {

DDS ALIVE INSTANCE STATE = 0x0001 << 0,

DDS NOT ALIVE DISPOSED INSTANCE STATE = 0x0001

<< 1,

DDS NOT ALIVE NO WRITERS INSTANCE STATE =

0x0001 << 2 }

Indicates is the samples are from a live DDSDataWriter ( p. 1113) or not.

Variables

const DDS InstanceStateMask DDS ANY INSTANCE STATE

Any instance state ALIVE INSTANCE STATE | NOT ALIVE -

DISPOSED INSTANCE STATE | NOT ALIVE NO WRITERS -

INSTANCE STATE.

const DDS InstanceStateMask DDS NOT ALIVE INSTANCE -

STATE

Not alive instance state NOT ALIVE DISPOSED INSTANCE STATE |

NOT ALIVE NO WRITERS INSTANCE STATE.

5.24.1 Detailed Description

DDS InstanceStateKind (p. 116) and associated elements

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

116 Module Documentation

5.24.2 Typedef Documentation

5.24.2.1 typedef DDS UnsignedLong DDS InstanceStateMask

A bit-mask (list) of instance states, i.e. DDS InstanceStateKind (p. 116).

5.24.3 Enumeration Type Documentation

5.24.3.1 enum DDS InstanceStateKind

Indicates is the samples are from a live DDSDataWriter (p. 1113) or not.

For each instance, the middleware internally maintains an instance state. The

instance state can be:

DDS ALIVE INSTANCE STATE (p. 117) indicates that (a) samples

have been received for the instance, (b) there are live DDSDataWriter

(p. 1113) entities writing the instance, and (c) the instance has not been

explicitly disposed (or else more samples have been received after it was

disposed).

DDS NOT ALIVE DISPOSED INSTANCE STATE (p. 117) indi-

cates the instance was explicitly disposed by a DDSDataWriter (p. 1113)

by means of the dispose operation.

DDS NOT ALIVE NO WRITERS INSTANCE STATE (p. 117)

indicates the instance has been declared as not-alive by the DDS-

DataReader (p. 1087) because it detected that there are no live DDS-

DataWriter (p. 1113) entities writing that instance.

The precise behavior events that cause the instance state to change depends on

the setting of the OWNERSHIP QoS:

If OWNERSHIP (p. 355) is set to DDS EXCLUSIVE -

OWNERSHIP QOS (p. 356), then the instance state becomes

DDS NOT ALIVE DISPOSED INSTANCE STATE (p. 117) only

if the DDSDataWriter (p. 1113) that ”owns” the instance explicitly

disposes it. The instance state becomes DDS ALIVE INSTANCE -

STATE (p.

117) again only if the DDSDataWriter (p. 1113) that owns

the instance writes it.

If OWNERSHIP (p. 355) is set to DDS SHARED OWNERSHIP -

QOS (p. 356), then the instance state becomes DDS NOT ALIVE -

DISPOSED INSTANCE STATE (p. 117) if any DDSDataWriter

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.24 Instance States 117

(p. 1113) explicitly disposes the instance. The instance state becomes

DDS ALIVE INSTANCE STATE (p. 117) as soon as any DDS-

DataWriter (p. 1113) writes the instance again.

The instance state available in the DDS SampleInfo (p. 912) is a snapshot of

the instance state of the instance at the time the collection was obtained (i.e.

at the time read or take was called). The instance s tate is therefore the same

for all samples in the returned collection that refer to the same instance.

Enumerator:

DDS ALIVE INSTANCE STATE Instance is currently in e xistence .

DDS NOT ALIVE DISPOSED INSTANCE STATE Not alive

disposed instance. The instance has been disposed by a DataWriter.

DDS NOT ALIVE NO WRITERS INSTANCE STATE Not

alive no writers for instance. None of the DDSDataWriter (p. 1113)

objects are currently alive (according to the LIVELINESS (p. 358))

are writing the instance.

5.24.4 Variable Documentation

5.24.4.1 const DDS InstanceStateMask DDS ANY INSTANCE -

STATE

Any instance state ALIVE INSTANCE STATE | NOT ALIVE DISPOSED -

INSTANCE STATE | NOT ALIVE NO WRITERS INSTANCE STATE.

Examples:

HelloWorld subscriber.cxx.

5.24.4.2 const DDS InstanceStateMask DDS NOT ALIVE -

INSTANCE STATE

Not alive instance state NOT ALIVE DISPOSED INSTANCE STATE | NOT -

ALIVE NO WRITERS INSTANCE STATE.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

118 Module Documentation

5.25 Infrastructure Module

Deﬁnes the abstract classes and the interfaces that are reﬁned by the other

modules. Contains common deﬁnitions such as return codes, status values, and

QoS policies.

Modules

Time Support

Time and duration t ypes and deﬁnes.

GUID Support

<<eXtension>> (p. 199) GUID type and deﬁnes.

Sequence Number Support

<<eXtension>> (p. 199) Sequence number type and deﬁnes.

Exception Codes

<<eXtension>> (p. 199) Exception codes.

Return Codes

Types of return codes.

Status Kinds

Kinds of communication status.

QoS Policies

Quality of Service (QoS) policies.

Entity Support

DDSEntity ( p. 1253), DDSListener ( p. 1318) and related items.

Conditions and WaitSets

DDSCondition ( p. 1075) and DDSWaitSet ( p. 1433) and related items.

WriteParams

<<eXtension>> (p. 199)

Octet Buﬀer Support

<<eXtension>> (p. 199) Octet buﬀer creation, cloning, and deletion.

Sequence Support

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.25 Infrastructure Module 119

The FooSeq ( p. 1494) interface allows you to work with variable-length col-

lections of homogeneous data.

String Support

<<eXtension>> (p. 199) String creation, cloning, assignment, and dele-

tion.

5.25.1 Detailed Description

Deﬁnes the abstract classes and the interfaces that are reﬁned by the other

modules. Contains common deﬁnitions such as return codes, status values, and

QoS policies.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

120 Module Documentation

5.26 Built-in Sequences

Deﬁnes sequences of primitive data type.

Classes

struct DDS CharSeq

Instantiates FooSeq (p. 1494) < DDS Char ( p. 299) >.

struct DDS WcharSeq

Instantiates FooSeq (p. 1494) < DDS Wchar ( p. 299) >.

struct DDS OctetSeq

Instantiates FooSeq (p. 1494) < DDS Octet ( p. 299) >.

struct DDS ShortSeq

Instantiates FooSeq (p. 1494) < DDS Short ( p. 299) >.

struct DDS UnsignedShortSeq

Instantiates FooSeq (p. 1494) < DDS UnsignedShort ( p. 299) >.

struct DDS LongSeq

Instantiates FooSeq (p. 1494) < DDS Long ( p. 300) >.

struct DDS UnsignedLongSeq

Instantiates FooSeq (p. 1494) < DDS UnsignedLong ( p. 300) > .

struct DDS LongLongSeq

Instantiates FooSeq (p. 1494) < DDS LongLong ( p. 300) > .

struct DDS UnsignedLongLongSeq

Instantiates FooSeq (p. 1494) < DDS UnsignedLongLong ( p. 300) >.

struct DDS FloatSeq

Instantiates FooSeq (p. 1494) < DDS Float ( p. 300) >.

struct DDS DoubleSeq

Instantiates FooSeq (p. 1494) < DDS Double ( p. 300) >.

struct DDS LongDoubleSeq

Instantiates FooSeq (p. 1494) < DDS LongDouble ( p. 300) >.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.26 Built-in Sequences 121

struct DDS BooleanSeq

Instantiates FooSeq (p. 1494) < DDS Boolean ( p. 301) >.

struct DDS StringSeq

Instantiates FooSeq (p. 1494) < char∗ > with value type semantics.

struct DDS WstringSeq

Instantiates FooSeq (p. 1494) < DDS Wchar ( p. 299)∗ >.

5.26.1 Detailed Description

Deﬁnes sequences of primitive data type.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

122 Module Documentation

5.27 Multi-channel DataWriters

APIs related to Multi-channel DataWriters.

5.27.1 What is a Multi-channel DataWriter?

A Multi-channel DDSDataWriter (p. 1113) is a DDSDataWriter (p. 1113)

that is conﬁgured to send data over multiple multicast addresses, according to

some ﬁltering criteria applied to the data.

To determine which multicast addresses will be used to send the data, the mid-

dleware evaluates a set of ﬁlters that are conﬁgured for the DDSDataWriter

(p. 1113). Each ﬁlter ”guards” a channel (a set of multicast addresses). Each

time a multi-channel DDSDataWriter (p. 1113) writes data, the ﬁlters are

applied. If a ﬁlter evaluates to true, the data is sent over that ﬁlter’s associated

channel (set of multicast addresses). We refer to this type of ﬁlter as a Channel

Guard ﬁlter.

5.27.2 Conﬁguration on the Writer Side

To conﬁgure a multi-channel DDSDataWriter (p. 1113), simply deﬁne a list

of all its channels in the DDS MultiChannelQosPolicy (p. 796).

The DDS MultiChannelQosPolicy (p. 796) is propagated along with

discovery traﬃc. The value of this policy is available in DDS -

PublicationBuiltinTopicData: :locator ﬁlter (p. 846).

5.27.3 Conﬁguration on the Reader Side

No special changes are required in a subscribing application to get data from a

multichannel DDSDataWriter (p. 1113). If you want the DDSDataReader

(p. 1087) to subscribe to only a subset of the channels, use a DDSContentFil-

teredTopic (p. 1081).

For more information on Multi-channel DataWriters, refer to the User’s

Manual.

5.27.4 Reliability with Multi-Channel DataWriters

5.27.4.1 Reliable Delivery

Reliable delivery is only guaranteed when the DDS -

PresentationQosPolicy::access scope (p. 826) is set to DDS -

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.27 Multi-channel DataWriters 123

INSTANCE PRESENTATION QOS (p. 352) and the ﬁlters in DDS -

MultiChannelQosPolicy (p. 796) are keyed-only based.

If any of the guard ﬁlters are based on non-key ﬁelds, RTI Connext only guar-

antees reception of the most recent data from the MultiChannel DataWriter.

5.27.4.2 Reliable Protocol Considerations

Reliability is maintained on a per-channel basis. Each channel has its

own reliability channel send queue. The size of that queue is limited

by DDS ResourceLimitsQosPolicy::max samples (p. 881) and/or DDS -

DataWriterResourceLimitsQosPolicy::max batches (p. 563).

The protocol parameters described in DDS DataWriterProtocolQosPoli cy

(p. 535) are applied per channel, with the following exceptions:

DDS RtpsReliableWriterProtocol t::low watermark (p. 892) and

DDS RtpsReliableWriterProtocol t::high watermark (p. 892): The low

watermark and high watermark control the queue levels (in number of samples)

that dete rmine when to switch between regular and fast heartbeat rates. With

MultiChannel DataWriters, high watermark and low watermark refer to the

DataWriter’s queue (not the reliability channel queue). Therefore, periodic

heartbeating cannot be controlled on a per-channel basis.

Important: With MultiChannel DataWriters, low watermark and high -

watermark refer to application samples even if batching is enabled. This be-

havior diﬀers from the one without MultiChannel DataWriters (where low -

watermark and high watermark refer to batches).

DDS RtpsReliableWriterProtocol t::heartbeats per max samples

(p. 896): This ﬁeld deﬁnes the number of heartbe ats per send queue. For

MultiChannel DataWriters, the value is applied per channel. However, the send

queue size that is used to calculate the a piggyback heartbeat rate is deﬁned per

DataWriter (see DDS ResourceLimitsQosPolicy:: max samples (p. 881))

Important: With MultiChannel DataWriters, heartbeats per max samples

refers to samples even if batching is enabled. This behavior diﬀers from the one

without MultiChannels DataWriters (where heartbeats per max samples refers

to batches).

With batching and MultiChannel DataWriters, the size of the

DataWriter’s send queue should be conﬁgured using DDS -

ResourceLimitsQosPolicy::max samples (p. 881) instead of max batches

DDS DataWriterResourceLimitsQosPolicy::max batches (p. 563) in

order to take advantage of heartbeats per max samples.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

124 Module Documentation

5.28 Pluggable Transports

APIs related to RTI Connext pluggable transports.

Modules

Using Transport Plugins

Conﬁguring transports used by RTI Connext.

Built-in Transport Plugins

Transport plugins delivered with RTI Connext.

5.28.1 Detailed Description

APIs related to RTI Connext pluggable transports.

5.28.2 Overview

RTI Connext has a pluggable transports architecture. The core of RTI Con-

next is transport agnostic; it does not make any assumptions about the actual

transports used to send and receive messages. Instead, the RTI Connext core

uses an abstract ”transport API” to interact with the transport pl ugins which

implement that API.

A transport plugin implements the abstract transport API and performs the

actual work of sending and receiving messages over a physical transport. A

collection of builtin plugins (see Built-in Transport Plugins (p. 136)) is

delivered with RTI Connext for commonly used transports. New transport

plugins can easily be created, thus enabling RTI Connext applications to run

over transports that may not even be conceived yet. This is a powerful capability

and that distinguishes RTI Connext from competing middleware approaches.

RTI Connext also provides a set of APIs for installing and conﬁguring transport

plugins to be used in an application. So that RTI Connext applications work

out of the box, a subset of the builtin transport plugins is preconﬁgured by

default (see DDS TransportBuiltinQosPolicy (p. 969)). You can ”turn-oﬀ”

some or all of the builtin transport plugins. In addition, you can conﬁgure other

transport plugins for use by the application.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.28 Pluggable Transports 125

5.28.3 Transport Aliases

In order to use a transport plugin instance in an RTI Connext application,

it must be registered with a DDSDomainParticipant (p. 1139). When you

refer to the transport plugin. The same alias strings can be used to register

more than one transport plugin.

You can register multiple transport plugins with a DDSDomainParticipant

(p. 1139). An alias symbolically refers to one or more transport plugins regis-

tered with the DDSDomainParticipant (p. 1139). Builtin transport plugin

instances can be referred to using preconﬁgured aliases (see TRANSPORT -

BUILTIN (p. 396)).

A transport plugin’s class name is automatically used as an implicit alias. It

can be used to refer to all the transport plugin instances of that class.

You can use aliases to refer to transport plugins, in order to specify:

- the transport plugins to use for discovery (see DDS -

DiscoveryQosPolicy::enabled transports (p. 583)), and for DDS-

DataWriter (p. 1113) and DDSDataReader (p. 1087) entities (see DDS -

TransportSelectionQosPol icy (p. 985)).

- the multicast addresses on which to receive discovery messages (see DDS -

DiscoveryQosPolicy::multicast receive addresses (p. 584)), and the mul-

ticast addresses and ports on which to receive user data (see DDS -

DataReaderQos::multicast (p. 520)).

- the unicast ports used for user data (see DDS -

TransportUnicastQosPolicy (p. 987)) on both DDSDataWriter (p. 1113)

and DDSDataReader (p. 1087) entities.

- the transport plugins used to parse an address string in a locator (Locator

Format (p. 389) and NDDS DISCOVERY PEERS (p. 388)).

A DDSDomainParticipant (p. 1139) (and contained its entities) start using a

transport plugin after the DDSDomainParticipant (p. 1139) is enabled (see

DDSEntity::enable (p. 1256)). An entity will use all the transport plugins

that match the speciﬁed transport QoS policy. All transport plugins are treated

uniformly, regardless of how they were created or registered; there is no notion

of some transports being more ”special” that others.

5.28.4 Transport Lifecycle

A transport plugin is owned by whoever created it. Thus, if you create and

responsible for deleting it by calling its destructor. Note that builtin transport

plugins (TRANSPORT BUILTIN (p. 396)) and transport plugins that are

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

126 Module Documentation

loaded through the PROPERTY (p. 436) QoS policy (see Loading Trans-

port Plugins through Property QoS Policy of Domain Participant

(p. 131)) are automatically managed by RTI Connext.

A user-created transport plugin must not be deleted while it is still in use by a

DDSDomainParticipant (p. 1139). This generally means that a user-created

transport plugin instance can only be deleted after the DDSDomainPartici-

pant (p. 1139) with which it was regis tered is delete d (see DDSDomainPar-

ticipantFactory::delete participant (p. 1236)). Note that a transport plugin

cannot be ”unregistered” from a DDSDomainPartic ipant (p. 1139).

A transport plugin instance cannot be registered with more than one DDS-

DomainParticipant (p. 1139) at a time. This requirement is necessary to

guarantee the multi-threaded safety of the transport API.

If the same physical transport resources are to be used with more than one

DDSDomainParticipant (p. 1139) in the same address space, the transport

plugin should be written in such a way so that it can be instantiated multiple

times—once for each DDSDomainParticipant (p. 1139) in the address space.

Note that it is always possible to write the transport plugin so that multiple

transport plugin instances share the same underlying res ources; however the

burden (if any) of guaranteeing multi-threaded safety to access shared resource

shifts to the transport plugin developer.

5.28.5 Transport Class Attributes

A transport plugin instance is associated with two kinds of attributes:

- the class attributes that are decided by the plugin writer; these are invariant

across all instances of the transport plugin class, and

- the instance attributes that can be set on a per instance basis by the transport

plugin user.

Every transport plugin must specify the following class attributes.

transport class id (see NDDS Transport Property t::classid (p. 1524))

Identiﬁes a transport plugin implementation class. It denotes a unique

”class” to which the transport plugin instance belongs. The class is

used to distinguish between diﬀerent transport plugin implementations.

Thus, a transport plugin vendor should ensure that its transport plugin

implementation has a unique class.

Two transport plugin instances report the same class iﬀ they have com-

patible implementations. Transport plugin instances with mismatching

classes are not allowed (by the RTI Connext Core) to communicate with

one another.

Multiple implementations (possibly from diﬀerent vendors) for a physical

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.28 Pluggable Transports 127

transport mechanism can co-exist in an RTI Connext application, provided

they use diﬀerent transport class IDs.

The class ID can also be used to distinguish between diﬀerent transport

protocols over the same physical transport network (e.g., UDP vs. TCP

over the IP routing infrastructure).

transport signiﬁcant address bit count (see NDDS Transp ort Property t::address bit count (p. 1524))

RTI Connext’s addressing is modeled after the IPv6 and uses 128-bit

addresses ( Address (p. 250) ) to route messages.

A transp ort plugin is expected to map the transport’s internal addressing

scheme to 128-bit addresses. In general, this mapping is likely to use only

N least signiﬁcant bits (LSB); these are speciﬁed by this attribute.

>-------------- netmask ----------------<

+---------------------------------------+----------------------------+

| Network Address | Transport Local Address |

+---------------------------------------+----------------------------+

>------------ N ------------<

address_bits_count

Only these bits are used

by the transport plugin.

The remaining bits of an address using the 128-bit address representa-

tion will be considered as part of the ”network address” (see Transport

Network Address (p. 128)) and thus ignored by the transport plugin’s

internal addressing scheme.

For unicast addresses, the transport plugin is expected to ignore the higher

(128 - NDDS Transport Property t::address bit count (p. 1524))

bits. RTI Connext is free to manipulate those bits freely in the addresses

passed in/out to the transport plugin APIs.

Theoretically, the signiﬁcant address bits count, N is related to the size of

the underlying transport network as follows:

address bits count >= ceil(log

(total addressable transport unicast interfaces))

The equality holds when the most compact (theoretical) internal address

mapping scheme is used. A practical address mapping s cheme may was te

some bits.

5.28.6 Transport Instance Attributes

The per instance attributes to conﬁgure the plugin instance are generally passed

in to the plugin constructor. These are deﬁned by the transport plugin writer,

and c an be used to:

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

128 Module Documentation

- customize the behavior of an instance of a transport plugin, including the send

and the receiver buﬀer sizes, the maximum message size, various transport level

classes of service (CoS), and so on.

- specify the resource values, network interfaces to use, various transp ort level

policies, and so on.

RTI Connext requires that every transport plugin instance must specify the

NDDS Transport Property t::message size max (p. 1525) and NDDS -

Transport Property t::gather send buﬀer count max (p. 1525).

It is up to the transport plugin developer to make these available for conﬁgura-

tion to transport plugin user.

Note that it is important that the instance attributes are ”compatible” between

the sending side and the receiving side of communicating applications using

diﬀerent instances of a transport plugin class. For example, if one side is con-

ﬁgured to send messages larger than can be received by the other side, then

communications via the plugin may fail.

5.28.7 Transport Network Address

The address bits not used by the transport plugin for its internal addressing

constitute its network address bits.

In order for RTI Connext to properly route the messages, each unicast inter-

face in the RTI Connext domain must have a unique address. RTI Connext

allows the user to s pecify the value of the network address when installing

a transport plugin via the NDDSTransp ortSupport::register transport()

(p. 1560) API.

The network address for a transport plugin should be chosen such that the re-

sulting fully qualiﬁed 128-bit address will be unique in the RTI Connext domain.

Thus, if two instances of a transport plugin are registered with a DDSDomain-

Participant (p. 1139), they will be at diﬀerent network addresses in order for

their unicast interfaces to have unique fully qualiﬁed 128-bit addresses. It is

also possible to create multiple transports with the same network address, as

it can be useful for certain use cases; note that this will require special entity

conﬁguration for most transports to avoid clashes in resource use (e.g. sockets

for UDPv4 transport).

5.28.8 Transport Send Route

By default, a transport plugin is conﬁgured to s end outgoing messages destined

to addresses in the network address range at which the plugin was registered.

RTI Connext allows the user to conﬁgure the routing of outgoing messages via

the NDDSTransportSupport::add send route() (p. 1562) API, so that a

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.28 Pluggable Transports 129

transport plugin will be used to send messages only to certain ranges of destina-

tion addresses. The method can be called multiple times for a transport plugin,

with diﬀerent address ranges.

+--------------------------------------------------------------------+

| Outgoing Address Range 1 -> Transport Plugin |

+--------------------------------------------------------------------+

| : -> : |

+--------------------------------------------------------------------+

| Outgoing Address Range K -> Transport Plugin |

+--------------------------------------------------------------------+

The user can set up a routing table to restrict the use of a transport plugin to

send messages to selected addresses ranges.

5.28.9 Transport Receive Route

By default, a transport plugin is conﬁgured to receive incoming messages des-

tined to addresses in the network address range at which the plugin was regis-

tered.

RTI Connext allows the user to conﬁgure the routing of incoming messages via

the NDDSTransportSupport::add receive route() (p. 1563) API, so that

a transport plugin will be used to receive messages only on certain ranges of

addresses. The method can be called multiple times for a transport plugin, with

diﬀerent address ranges.

+--------------------------------------------------------------------+

| Transport Plugin <- Incoming Address Range 1 |

+--------------------------------------------------------------------+

| : <- : |

+--------------------------------------------------------------------+

| Transport Plugin <- Incoming Address Range M |

+--------------------------------------------------------------------+

The user can set up a routing table to restrict the use of a transport plugin

to receive messages from selected ranges. For example, the user may restrict a

transport plugin to

- receive messages from a certain multicast address range.

- receive messages only on certain unicast interfaces (when multiple unicast

interfaces are available on the transport plugin).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

130 Module Documentation

5.29 Using Transport Plugins

Conﬁguring transports used by RTI Connext.

Classes

class NDDSTransportSupport

<<inter face>> (p. 199) The utility class used to conﬁgure RTI Connext

pluggable transports.

Typedefs

typedef NDDS TRANSPORT HANDLE TYPE NATIVE NDDS -

Transport Handle t

An opaque type representing the handle to a transport plugin registered with

a DDSDomainParticipant ( p. 1139).

typedef NDDS Transport Plugin ∗(∗ NDDS Transport create plugin

)(NDDS Transport Address t ∗default network address out, const

struct DDS PropertyQosPolicy ∗property in)

Function prototype for creating plugin through DDS PropertyQosPolicy

( p. 834).

Functions

DDS Boolean NDDS Transport Handle is nil (const NDDS -

Transport Handle t ∗self)

Is the given transport handle the NIL transport handle?

Variables

const NDDS Transport Handle t NDDS TRANSPORT -

HANDLE NIL

The NIL transport handle.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.29 Using Transport Plugins 131

5.29.1 Detailed Description

Conﬁguring transports used by RTI Connext.

There is more than one way to install a transport plugin for use with RTI

Connext:

If it is a builtin transport plugin, by specifying a bitmask in DDS -

TransportBuiltinQosPolicy (p. 969) (see Buil t-i n Transport Plu-

gins (p. 136))

For all other non-builtin transport plugins, by dynamically loading the plu-

gin through PROPERTY (p. 436) QoS policy settings of DDSDomain-

Participant (p. 1139) (on UNIX, Solaris and Windows systems only) (see

Loading Transport Plugins through Property QoS Policy of Do-

main Participant (p. 131))

By explicitly creating a transport plugin and registering the plugin with

a DDSDomainParticipant (p. 1139) through NDDSTransportSup-

port::register transport (p. 1560) (for both builtin and non-builtin plu-

gins)

In the ﬁrst two cases, the lifecycle of the transport plugin is automatically

managed by RTI Connext. In the last case, user is responsible for deleting the

transport plugin after the DDSDomainParticipant (p. 1139) is deleted. See

Transport Lifecycle (p. 125) for details.

5.29.2 Loading Transport Plugins through Property QoS

Policy of Domain Participant

On UNIX, Solaris and Windows operating systems, a non-builtin transport plu-

gin written in C/C++ and built as a dynamic-link library (∗.dll/∗.so) can be

loaded by RTI Connext through the PROPERTY (p. 436) QoS policy set-

tings of the DDSDomainParticipant (p. 1139). The dynamic-link library

(and all the dependent libraries) need to be in the path during runtime (in

LD LIBRARY PATH environment variable on Linux/Solaris systems,and in

PATH environment variable for Windows systems).

To allow dynamic loading of the transport plugin, the transport plugin must

implement the RTI Connext abstract transp ort API and must provide a func-

tion with the signature NDDS Transport create plugin (p. 132) that can

be called by RTI Connext to create an instance of the transport plugin. The

name of the dynamic library that contains the transport plugin implementa-

tion, the name of the function and properties that can b e used to create the

plugin, and the aliases and network address that are used to register the plu-

gin can all be speciﬁed through the PROPERTY (p. 436) QoS policy of the

DDSDomainParticipant (p. 1139).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

132 Module Documentation

The following table lists the property names that are used to load the transport

plugins dynamically:

A transport plugin is dynamically created and registered to the DDSDomain-

Participant (p. 1139) by RTI C onnext when:

the DDSDomainParticipant (p. 1139) is enabled,

the ﬁrst DataWriter/DataReader is created, or

you lookup a builtin DataReader (DDSSubscrib er::l ookup -

datareader (p. 1404)),

whichever happens ﬁrst.

Any changes to the transport plugin related properties in PROPERTY (p. 436)

QoS policy after the transport plugin has been registered with the DDSDo-

mainParticipant (p. 1139) will have no eﬀect.

See also:

Transport Use Cases (p. 181)

5.29.3 Typedef Documentation

5.29.3.1 typedef NDDS TRANSPORT HANDLE TYPE NATIVE

NDDS Transport Handle t

An opaque type representing the handle to a transport plugin registered with a

DDSDomainParticipant (p. 1139).

A transport handle represents the association between a DDSDomainPartic-

ipant (p. 1139) and a transport plugin.

5.29.3.2 typedef NDDS Transport Plugin∗(∗ NDDS -

Transport create plugin)(NDDS Transport Address t

∗default network address out, const struct

DDS PropertyQosPoli cy ∗property in)

Function prototype for creating plugin through DDS PropertyQosPolicy

(p. 834).

By specifying some predeﬁned property names in DDS PropertyQosPolicy

(p. 834), RTI Connext can call a function from a dynamic library to create a

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.29 Using Transport Plugins 133

transport plugin and register the returned plugin with a DDSDomainParti c-

ipant (p. 1139).

This is the function prototype of the function as speciﬁed in ”<TRANSPORT -

PREFIX>.create function” of DDS PropertyQosPolicy (p. 834) QoS policy

that will be called by RTI Connext to create the transport plugin. See Loading

Transport Plugins through Property QoS Policy of Domain Partici-

pant (p. 131) for details.

Parameters:

network address out <<out>> ( p. 200) Optional output parameter.

If the network address is not speciﬁed in ”<TRANSPORT -

PREFIX>.network address” in DDS PropertyQosPolicy (p. 834),

this is the default network address that is used to regis-

ter the re turned transport plugin using NDDSTransportSup-

port::register transport (p. 1560). This parameter will never be

null. The default value is a zeroed-out network address.

property in <<in>> ( p. 200) property in contains all the name-

value pair properties that matches the format ”<TRANSPORT -

PREFIX>.<prope rty name>” in DDS PropertyQosPolicy

(p. 834) that can be used to create the transport plugin. Only

<prop e rty name> is passed in - the plugin preﬁx will be stripped out

in the property name. Note: predeﬁned <TRANSPORT PREFIX>

prop e rties ”library”, ”create function”, ”aliases” and ”network -

address” will not be passed to this function. This parameter will

never be null.

Returns:

Upon success, a valid non-NIL transport plugin. NIL upon failure.

5.29.4 Function Documentation

5.29.4.1 DDS Boolean NDDS Transport Handle is nil (const

NDDS Transport Handle t ∗ self)

Is the given transport handle the NIL transport handle?

Returns:

DDS BOOLEAN TRUE (p. 298) if the given transport handle is

equal to NDDS TRANSPORT HANDLE NIL (p. 134) or DDS -

BOOLEAN FALSE (p. 299) otherwise.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

134 Module Documentation

5.29.5 Variable Documentation

5.29.5.1 const NDDS Transport Handle t

NDDS TRANSPORT HANDLE NIL

The NIL transport handle.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.29 Using Transport Plugins 135

Property Name Description Required?

dds.transp ort.load -

plugins

Comma-separated

strings indicating the

preﬁx names of all

plugins that will be

loaded by RTI

Connext. Up to 8

plugins may be

speciﬁed. For example,

”dds.transp ort.WAN.wan1,

dds.transp ort.DTLS.dtls1”,

In the following

examples,

<TRANSPORT -

PREFIX> is used to

indicate one element of

this string that is used

as a preﬁx in the

prop e rty names for all

the settings that are

related to the plugin.

<TRANSPORT -

PREFIX> must begin

with ”dds.transport.”

(such as

”dds.transp ort.mytransport”).

YES

<TRANSPORT -

PREFIX>.library

Should be set to the

name of the dynamic

library (∗.so for

Unix/Solaris, and ∗.dll

for Windows) that

contains the transport

plugin implementation.

This library (and all

the other dependent

dynamic libraries)

needs to be in the path

during run time for

used by RTI Connext

(in the LD -

LIBRARY PATH

environment variable

on UNIX/Solaris

systems, in PATH for

Windows systems).

YES

<TRANSPORT -

PREFIX>.create -

function

Should be set to the

name of the function

with the prototype of

NDDS Transport -

create plugin (p. 132)

that can be called by

RTI Connext to create

an instance of the

plugin. The resulting

transport plugin will

then be registered by

RTI Connext through

NDDSTransport-

Support::register -

transport

(p. 1560)

YES

<TRANSPORT -

PREFIX>.aliases

Used to register the

transport plugin

returned by

NDDS Transport -

create plugin (p. 132)

(as speciﬁed by

<TRANSPORT -

PREFIX>.create -

function) to the

DDSDomainPartici-

pant (p. 1139). Refer

to aliases in

parameter in

NDDSTransport-

Support::register -

transport (p. 1560)

for details. Aliases

should be speciﬁed as

comma separated

string, w ith each

comma delimiting an

alias. If it is not

speciﬁed,

<TRANSPORT -

PREFIX> is used as

the default alias for the

plugin

<TRANSPORT -

PREFIX>.network -

address

Used to register the

transport plugin

returned by

NDDS Transport -

create plugin (p. 132)

(as speciﬁed by

<TRANSPORT -

PREFIX>.create -

function) to the

DDSDomainPartici-

pant (p. 1139). Refer

network address in

parameter in

NDDSTransport-

Support::register -

transport (p. 1560)

for details. If it is not

speciﬁed, the net-

work address out

output parameter from

NDDS Transport -

create plugin (p. 132)

is used. The default

value is a zeroed out

network address.

<TRANSPORT -

PREFIX>.<prop erty -

name>

Prop e rty that is passed

into

NDDS Transport -

create plugin (p. 132)

(as speciﬁed by

<TRANSPORT -

PREFIX>.create -

function) for creating

the transport plugin.

This property

name-value pair will be

passed to

NDDS Transport -

create plugin (p. 132)

after stripping out

<TRANSPORT -

PREFIX> from the

prop e rty name. The

parsing of this prop e rty

and c onﬁguring the

transport using this

prop e rty should be

handled by the

implementation of each

transport plugin.

Multiple

<TRANSPORT -

PREFIX>.<prope rty -

name> can be

speciﬁed.

Note: ”library”,

”create function”,

”aliases” and

”network address”

cannot be used as the

<prop e rty name> due

to conﬂicts with other

builtin property names.

Table 5.5: Properties for dynamically loading and registering transport plugins

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

136 Module Documentation

5.30 Built-in Transport Plugins

Transport plugins delivered with RTI Connext.

Modules

Shared Memory Transport

Built-in transport plug-in for inter-process communications using shared

memory (NDDS TRANSPORT CLASSID SHMEM ( p. 261)).

UDPv4 Transport

Built-in transport plug-in using UDP/IPv4 (NDDS TRANSPORT -

CLASSID UDPv4 ( p. 268)).

UDPv6 Transport

Built-in transport plug-in using UDP/IPv6 (NDDS TRANSPORT -

CLASSID UDPv6 ( p. 278)).

5.30.1 Detailed Description

Transport plugins delivered with RTI Connext.

The TRANSPORT BUILTIN (p. 396) speciﬁes the collection of transport

plugins that can be automatically conﬁgured and managed by RTI Connext as

a convenience to the user.

These transport plugins can simply be turned ”on” or ”oﬀ” by a specifying

a bitmask in DDS TransportBuiltinQosPolicy (p. 969), thus bypassing the

steps for se tting up a transport plugin. RTI Connext preconﬁgures the transport

plugin properties, the network address, and the aliases to ”factory deﬁned”

values.

If a builtin transport plugin is turned ”on” in DDS -

TransportBuiltinQosPolicy (p. 969), the plugin is implicitly created

and registered to the corresponding DDSDomainParticipant (p. 1139) by

RTI Connext when:

the DDSDomainParticipant (p. 1139) is enabled,

the ﬁrst DataWriter/DataReader is created, or

you lookup a builtin DataReader (DDSSubscrib er::l ookup -

datareader (p. 1404)),

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.30 Built-in Transport Plugins 137

whichever happens ﬁrst.

Each builtin transport contains its own set of properties. For example, the

::UDPv4 Transport (p. 265) allows the application to specify whether or not

multicast is supported, the maximum size of the message, and provides a mech-

anism for the application to ﬁlter out network interfaces.

The builtin transport plugin properties can be changed by the metho d

NDDSTransportSupport::set builtin transport property() (p. 1564) or

by using the PROPERTY (p. 436) QoS policy associated with the DDS-

DomainParticipant (p. 1139). Builtin transport plugin properties speci-

ﬁed in DDS PropertyQosPolicy (p. 834) always overwrite the ones sp ec i-

ﬁed through NDDSTransportSupport::set builtin transport property()

(p. 1564). Refer to the speciﬁc builtin transport for the list of property names

that can be speciﬁed through PROPERTY (p. 436) QoS policy.

Any changes to the builtin transport properties after the builtin transports have

been registered with will have no eﬀect.

See also:

NDDSTransportSupport::set builtin transport property()

(p. 1564) DDS PropertyQosPolicy (p. 834)

The built-in transport plugins can also be instantiated and registered by the

user, following the steps for Registering a transport with a participant

(p. 183). This is useful when the application needs diﬀerent values for the net-

work addresses.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

138 Module Documentation

5.31 Conﬁguration Utilities

Utility API’s independent of the DDS standard.

Classes

class NDDSConﬁgVersion

<<inter face>> (p. 199) The version of an RTI Connext distribution.

class NDDSConﬁgLoggerDevice

<<inter face>> (p. 199) Logging device interface. Use for user-deﬁned log-

ging devices.

class NDDSConﬁgLogger

<<inter face>> (p. 199) The singleton type used to conﬁgure RTI Connext

logging.

struct NDDS Conﬁg LibraryVersion t

The version of a single library shipped as part of an RTI Connext distribution.

struct NDDS Conﬁg LogMessage

Log message.

Enumerations

enum NDDS Conﬁg LogVerbosity {

NDDS CONFIG LOG VERBOSITY SILENT,

NDDS CONFIG LOG VERBOSITY ERROR,

NDDS CONFIG LOG VERBOSITY WARNING,

NDDS CONFIG LOG VERBOSITY STATUS LOCAL,

NDDS CONFIG LOG VERBOSITY STATUS REMOTE,

NDDS CONFIG LOG VERBOSITY STATUS ALL }

The verbosities at which RTI Connext diagnostic information is logged.

enum NDDS Conﬁg LogLevel {

NDDS CONFIG LOG LEVEL ERROR,

NDDS CONFIG LOG LEVEL WARNING,

NDDS CONFIG LOG LEVEL STATUS LOCAL,

NDDS CONFIG LOG LEVEL STATUS REMOTE,

NDDS CONFIG LOG LEVEL DEBUG }

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.31 Conﬁguration Utilities 139

Level category assigned to RTI Connext log messages returned to an output

device.

enum NDDS Conﬁg LogCategory {

NDDS CONFIG LOG CATEGORY PLATFORM,

NDDS CONFIG LOG CATEGORY COMMUNICATION,

NDDS CONFIG LOG CATEGORY DATABASE,

NDDS CONFIG LOG CATEGORY ENTITIES,

NDDS CONFIG LOG CATEGORY API }

Categories of logged messages.

enum NDDS Conﬁg LogPrintFormat { ,

NDDS CONFIG LOG PRINT FORMAT DEFAULT,

NDDS CONFIG LOG PRINT FORMAT TIMESTAMPED,

NDDS CONFIG LOG PRINT FORMAT VERBOSE,

NDDS CONFIG LOG PRINT FORMAT VERBOSE -

TIMESTAMPED,

NDDS CONFIG LOG PRINT FORMAT DEBUG,

NDDS CONFIG LOG PRINT FORMAT MINIMAL,

NDDS CONFIG LOG PRINT FORMAT MAXIMAL }

The format used to output RTI Connext diagnostic information.

5.31.1 Detailed Description

Utility API’s independent of the DDS standard.

5.31.2 Enumeration Type Documentation

5.31.2.1 enum NDDS Conﬁg LogVerbosity

The verbosities at which RTI Connext diagnostic information is logged.

Enumerator:

NDDS CONFIG LOG VERBOSITY SILENT No further output

will be logged.

NDDS CONFIG LOG VERBOSITY ERROR Only error mes-

sages will be logged.

An error indicates s ome thing wrong in the functioning of RTI Connext.

The most common cause of errors is incorrect conﬁguration.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

140 Module Documentation

NDDS CONFIG LOG VERBOSITY WARNING Both error and

warning m ess ages will be logged.

A warning indicates that RTI Connext is taking an action that may

or may not be what you intended. Some conﬁguration information is

also logged at this verbosity to aid in debugging.

NDDS CONFIG LOG VERBOSITY STATUS LOCAL Errors,

warnings, and verbose information about the lifecycles of local RTI

Connext objects will be logged.

NDDS CONFIG LOG VERBOSITY STATUS REMOTE

Errors, warnings, and verbose information about the lifecycles of

remote RTI Connext objects will be logged.

NDDS CONFIG LOG VERBOSITY STATUS ALL Errors,

warnings, verbose information about the lifecycles of local and remote

RTI Connext objects, and periodic information about RTI Connext

threads will be logged.

5.31.2.2 enum NDDS Conﬁg LogLevel

Level category assigned to RTI Connext log messages returned to an output

device.

Enumerator:

NDDS CONFIG LOG LEVEL ERROR The message describes an

error.

An error indicates s ome thing wrong in the functioning of RTI Connext.

The most common cause of errors is incorrect conﬁguration.

NDDS CONFIG LOG LEVEL WARNING The message describes

a warning.

A warning indicates that RTI Connext is taking an action that may

or may not be what you intended. Some conﬁguration information is

also logged at this verbosity to aid in debugging.

NDDS CONFIG LOG LEVEL STATUS LOCAL The message

contains info about the lifecycles of local RTI Connext objects will be

logged.

NDDS CONFIG LOG LEVEL STATUS REMOTE The message

contains info about the lifecycles of remote RTI Connext objects will

be logged.

NDDS CONFIG LOG LEVEL DEBUG The message contains de-

bug info that might be relevant to your application.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.31 Conﬁguration Utilities 141

5.31.2.3 enum NDDS Conﬁg LogCategory

Categories of logged messages.

The DDSLogger::get verbosity by category and DDSLogger::set verbosity by -

category can be used to specify diﬀerent verbosities for diﬀerent categories of

messages.

Enumerator:

NDDS CONFIG LOG CATEGORY PLATFORM Log messages

pertaining to the underlying platform (hardware and OS) on which

RTI Connext is running are in this category.

NDDS CONFIG LOG CATEGORY COMMUNICATION Log

messages pertaining to data serialization and deserialization and

network traﬃc are in this category.

NDDS CONFIG LOG CATEGORY DATABASE Log messages

pertaining to the internal database in which RTI Connext objects are

stored are in this category.

NDDS CONFIG LOG CATEGORY ENTITIES Log messages

pertaining to local and remote entities and to the discovery process

are in this category.

NDDS CONFIG LOG CATEGORY API Log messages pertaining

to the API layer of RTI Connext (such as method argument validation)

are in this category.

5.31.2.4 enum NDDS Conﬁg LogPrintFormat

The format used to output RTI Connext diagnostic information.

Enumerator:

NDDS CONFIG LOG PRINT FORMAT DEFAULT Print mes-

sage, method name, and activity context (default).

NDDS CONFIG LOG PRINT FORMAT TIMESTAMPED

Print message, method name, activity context, and timestamp.

NDDS CONFIG LOG PRINT FORMAT VERBOSE Print mes-

sage with all available context information (includes thread identiﬁer,

activity context).

NDDS CONFIG LOG PRINT FORMAT VERBOSE TIMESTAMPED

Print message with all available context information, and timestamp.

NDDS CONFIG LOG PRINT FORMAT DEBUG Print a set of

ﬁeld that may be useful for internal debug.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

142 Module Documentation

NDDS CONFIG LOG PRINT FORMAT MINIMAL Print only

message number and method name.

NDDS CONFIG LOG PRINT FORMAT MAXIMAL Print all

available ﬁelds.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.32 Unsupported Utilities 143

5.32 Unsupported Utilities

Unsupp orted APIs used by examples in the RTI Connext distribution as well

as in rtiddsgen-generated examples.

Classes

class NDDSUtility

Unsupported utility APIs.

5.32.1 Detailed Description

Unsupp orted APIs used by examples in the RTI Connext distribution as well

as in rtiddsgen-generated examples.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

144 Module Documentation

5.33 Durability and Persistence

APIs related to RTI Connext Durability and Persistence. RTI Connext oﬀers

the following mechanisms for achieving durability and persistence:

Durable Writer History (p. 144)

Durable Reader State (p. 144)

Data Durability (p. 145)

To use any of these features, you need a relational database, which is not

included with RTI Connext. Supported databases are listed in the Release

Notes.

These three features can be used separately or in combination.

5.33.1 Durable Writer History

This feature allows a DDSDataWriter (p. 1113) to locally persist its local his-

tory cache so that it can survive shutdowns, crashes and restarts. When an

application restarts, each DDSDataWriter (p. 1113) that has been conﬁgured

to have durable writer history automatically loads all the data in its history

cache from disk and can carry on sending data as if it had never stopped ex-

ecuting. To the rest of the system, it will appear as if the DDSDataWriter

(p. 1113) had been temporarily disconnected from the network and then reap-

peared.

See also:

Conﬁguring Durable Writer History (p. 146)

5.33.2 Durable Reader State

This feature allows a DDSDataReader (p. 1087) to locally persists its state

and remember the data it has already received. When an application restarts,

each DDSDataReader (p. 1087) that has been conﬁgured to have durable

reader state automatically loads its state from disk and can carry on receiving

data as if it had never stopped executing. Data that had already been received

by the DDSDataReader (p. 1087) before the restart will be suppressed so it

is not sent over the network.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.33 Durability and Persistence 145

5.33.3 Data Durability

This feature is a full implementation of the OMG DDS Pers istence Proﬁle. The

DURABILITY (p. 348) QoS lets an application conﬁgure a DDSDataWriter

(p. 1113) such that the information written by the DDSDataWriter (p. 1113)

survive s beyond the lifetime of the DDSDataWriter (p. 1113). In this man-

ner, a late-joining DDSDataReader (p. 1087) can subscribe and receive the

information even after the DDSDataWriter (p. 1113) application is no longer

executing. To use this feature, you need RTI Persistence Service – an optional

product that can be purchased separately.

5.33.4 Durability and Persistence Based on Virtual GUID

Every modiﬁcation to the global dataspace made by a DDSDataWriter

(p. 1113) is identiﬁed by a pair (virtual GUID, sequence number).

The virtual GUID (Global Unique Identiﬁer) is a 16-byte character identi-

ﬁer associated with a DDSDataWriter (p. 1113) or DDSDataReader

(p. 1087); it is used to uniquely identify this entity in the global data space.

The sequence number is a 64-bit identiﬁer that identiﬁes changes published

by a speciﬁc DDSDataWriter (p. 1113).

Several DDSDataWriter (p. 1113) entities can be conﬁgured with the same

virtual GUID. If each of these DDSDataWriter (p. 1113) entities publishes a

sample with sequence number ’0’, the sample will only be received once by the

DDSDataReader (p. 1087) entities subscribing to the content published by

the DDSDataWriter (p. 1113) entities.

RTI Connext also uses the virtual GUID (Global Unique Identiﬁer) to associate

a persisted state (state in permanent storage) to the corresponding DDS entity.

For example, the history of a DDSDataWriter (p. 1113) will be persisted in

a database table with a name generated from the virtual GUID of the DDS-

DataWriter (p. 1113). If the DDSDataWriter (p. 1113) is restarted, it must

have associated the same virtual GUID to restore its previous history.

Likewise, the state of a DDSDataReader (p. 1087) will be persisted in a

database table whose name is generated from the DDSDataReader (p. 1087)

virtual GUID

A DDSDataWriter (p. 1113)’s virtual GUID can be conﬁgured using DDS -

DataWriterProtocolQosPolicy::virtual guid (p. 536). Similarly, a DDS-

DataReader (p. 1087)’s virtual GUID can be conﬁgured using DDS -

DataReaderProtocolQosPolicy::virtual guid (p. 502).

The DDS PublicationBuiltinTopicData (p. 839) and DDS -

SubscriptionBuiltinTopicData (p. 936) structures include the virtual

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

146 Module Documentation

GUID associated with the discovered publication or subscription.

Refer to the User’s Manual for additional use cases.

See also:

DDS DataWriterProtocolQosPolicy::virtual guid (p. 536) DDS -

DataReaderProtocolQosPolicy::virtual guid (p. 502).

5.33.5 Conﬁguring Durable Writer History

To conﬁgure a DDSDataWriter (p. 1113) to have durable writer history, use

the PROPERTY (p. 436) QoS policy associated with the DDSDataWriter

(p. 1113) or the DDSDomainParticipant (p. 1139).

Properties deﬁned for the DDSDomainParticipant (p. 1139) will be ap-

plied to all the DDSDataWriter (p. 1113) objects belonging to the DDSDo-

mainParticipant (p. 1139), unless the property is overwritten by the DDS-

DataWriter (p. 1113).

See also:

DDS PropertyQosPoli cy (p. 834)

The following table lists the supported durable writer history properties.

5.33.6 Conﬁguring Durable Reader State

To conﬁgure a DDSDataReader (p. 1087) with durable reader state, use

the PROPERTY (p. 436) QoS policy associated with the DDSDataReader

(p. 1087) or DDSDomainParticipant (p. 1139).

A property deﬁned in the DDSDomainParticipant (p. 1139) will be applica-

ble to all the DDSDataReader (p. 1087) belonging to the DDSDomainPar-

ticipant (p. 1139) unless it is overwritten by the DDSDataReader (p. 1087).

See also:

DDS PropertyQosPoli cy (p. 834)

The following table lists the supported durable reader state properties.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.33 Durability and Persistence 147

5.33.7 Conﬁguring Data Durability

RTI Connext implements DDS TRANSIENT DURABILITY QOS

(p. 349) and DDS PERSISTENT DURABILITY QOS (p. 349) durability

using RTI Persistence Service, available for purchase as a separate RTI product.

For more information on RTI Persistence Service, refer to the User’s Manual,

or the RTI Persistence Service API Reference HTML documentation.

See also:

DURABILITY (p. 348)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

148 Module Documentation

Property Description

dds.data writer.history.plugin name Must be set to ”dds.data -

writer.history.odbc plugin.builtin”

to enable durable writer history in

the DataWriter. This property is

required.

dds.data writer.history.odbc -

plugin.dsn

The ODBC DSN (Data Source

Name) associated with the database

where the writer history must be

persisted. This property is required.

dds.data writer.history.odbc -

plugin.driver

This property tells RTI Connext

which ODBC driver to load. If the

prop e rty is not speciﬁed, RTI

Connext will try to use the standard

ODBC driver manager library:

UnixOdb c (odbc32.dll) on

UNIX/Linux s ystems ; the Windows

ODBC driver manager (libodbc.so)

on Windows systems).

dds.data writer.history.odbc -

plugin.username

Conﬁgures the username used to

connect to the database. This

prop e rty is not used if it is

unspeciﬁed. There is no default

value.

dds.data writer.history.odbc -

plugin.password

Conﬁgures the password used to

connect to the database. This

prop e rty is not used if it is

unspeciﬁed. There is no default

value.

dds.data writer.history.odbc -

plugin.shared

If set to 1, RTI Connext creates a

single connection per DSN that will

be shared across DataWriters within

the same Publisher.

If set to 0 (the default), a

DDSDataWriter (p. 1113) will

create its own database connection.

Default: 0 (false)

dds.data writer.history.odbc -

plugin.instance cache max size

These properties conﬁgure the

resource limits associated with the

ODBC writer history caches. To

minimize the number of accesses to

the database, RTI Connext uses two

caches, one for samples and one for

instances. The initial and maximum

sizes of these caches are conﬁgured

using these properties. The resource

limits initial instances,

max instances, initial samples,

max samples and

max samples per instance in the

DDS ResourceLimitsQosPolicy

(p. 879) are used to conﬁgure the

maximum number of samples and

instances that can be stored in the

relational database. Default: DDS -

ResourceLimitsQosPolicy::max -

instances

(p. 882)

dds.data writer.history.odbc -

plugin.instance cache init size

See description above. Default:

DDS -

ResourceLimitsQosPolicy::initial -

instances

(p. 883)

dds.data writer.history.odbc -

plugin.sample cache max size

See description above. Default: 32

(the minimum)

dds.data writer.history.odbc -

plugin.sample cache init size

See description above. Default: 32

dds.data writer.history.odbc -

plugin.restore

This property indicates whether or

not the persisted writer history

must be restored once the

DDSDataWriter (p. 1113) is

restarted. If the value is 0, the

content of the database associated

with the DDSDataWriter

(p. 1113) being restarted will be

deleted. If the value is 1, the

DDSDataWriter (p. 1113) will

restore its previous state from the

database content. Default: 1

dds.data writer.history.odbc -

plugin.in memory state

This property determines how much

state will be kept in memory by the

ODBC writer history in order to

avoid accessing the database.

When in memory state is equal to

1, instance cache max size is always

equal to DDS -

ResourceLimitsQosPolicy::max

instances (p. 882) (it cannot be

changed). In addition, the ODBC

writer history will keep in memory a

ﬁxed state overhead of 24 bytes per

sample. In this operating mode, the

ODBC writer history provides the

best performance. However, the

restore operation will be slower and

the maximum number of samples

that the writer history can manage

will be limited by the available

physic al memory.

If in memory state is equal to 0, all

the state will be kept in the

underlying database. In this

operating mode, the maximum

number of samples in the writer

history w ill not be limited by the

physic al memory available unless

the underlying database is an

in-memory database (TimesTen).

Default: 1

Table 5.6: Durable Writer History Properties

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.33 Durability and Persistence 149

Property Description

dds.data reader.state.odbc.dsn The ODBC DSN (Data Source

Name) associated with the database

where the DDSDataReader

(p. 1087) state must be persisted.

This property is required.

dds.data reader.state.ﬁlter -

redundant samples

To enable durable reader state, this

prop e rty must be set to 1.

Otherwise, the reader state will not

be kept and/or persisted. When the

reader state is not maintained, RTI

Connext does not ﬁlter duplicate

samples that may be coming from

the same virtual writer. By default,

this property is set to 1.

dds.data reader.state.odbc.driver This property is used to indicate

which ODBC driver to load. If the

prop e rty is not speciﬁed, RTI

Connext will try to use the standard

ODBC driver manager library:

UnixOdb c (odbc32.dll) on

UNIX/Linux systems; the Windows

ODBC driver manager (libodbc.so)

on Windows systems).

dds.data -

reader.state.odbc.username

This property conﬁgures the

username used to connect to the

database. This property is not used

if it is unspeciﬁed. There is no

default value.

dds.data reader.state.odbc.password This property conﬁgures the

password used to connect to the

database. This property is not used

if it is unspeciﬁed. There is no

default value.

dds.data reader.state.restore This property indicates if the

persisted DDSDataReader

(p. 1087) state must be restored or

not once the DDSDataReader

(p. 1087) is restarted. If this

prop e rty is 0, the previous state will

be deleted from the database. If it is

1, the DDSDataReader (p. 1087)

will restore its previous state from

the database content. Default: 1

dds.data reader.state.checkpoint -

frequency

This property controls how often

the reader state is stored in the

database. A value of N means to

store the state once every N

samples.

A high frequency will provide better

performance. However, if the reader

is restarted it may receive some

duplicate s amples. These samples

will be ﬁltered by the middleware

and they will not be propagated to

the application.

Default: 1

dds.data reader.state.persistence -

service.request depth

This property indicates the number

of most recent historical samples

that the persisted

DDSDataReader (p. 1087) wants

to receive when it starts up.

Default: 0

Table 5.7: Durable Reader State Properties

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

150 Module Documentation

5.34 System Properties

System Properties. RTI Connext uses the DDS PropertyQosPolicy (p. 834)

of a DomainParticipant to maintain a set of properties that provide system

information such as hostname.

Unless the default DDS DomainParticipantQos (p. 588) value is over-

written, the system properties are automatically set in the DDS -

DomainParticipantQos (p. 588) obtained by calling the method DDSDo-

mainParticipantFactory::get default participant qos (p. 1224) or using

the constant DDS PARTICIPANT QOS DEFAULT (p. 35).

System properties are also automatically set in the DDS -

DomainParticipantQos (p. 588) loaded from an XML QoS proﬁle unless

you disable property inheritance using the attribute inherit in the XML tag

<property>.

By default, the system properties are propagated to other Domain-

Participants in the system and can be accessed through DDS -

ParticipantBuiltinTopicData::property (p. 817).

You can disable the propagation of individual properties by setting

the ﬂag DDS Property t::propagate (p. 833) to DDS BOOLEAN -

FALSE (p. 299) or by removing the property using the method DDS -

PropertyQosPolicyHelper::remove property.

The number of system properties set on the DDS DomainParticipantQos

(p. 588) is platform speciﬁc.

5.34.1 System Properties List

The following table lists the supported system properties.

Property Name Description

dds.sys info.hostname Hostname

dds.sys info.process id Process ID

5.34.2 System Resource Consideration

System properties are aﬀected by the resource limits DDS -

DomainParticipantResourceLimitsQosPolicy::participant -

property list max length (p. 610) and DDS -

DomainParticipantResourceLimitsQosPolicy::participant property -

string max length (p. 610).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.35 Conﬁguring QoS Proﬁles with XML 151

5.35 Conﬁguring QoS Proﬁles with XML

APIs related to XML QoS Proﬁles.

5.35.1 Loading QoS Proﬁles from XML Resources

A ’QoS proﬁle’ is a group of QoS settings, speciﬁed in XML format. By using

QoS proﬁles, you can change QoS settings without recompiling the application.

The Qos proﬁles are loaded the ﬁrst time any of the following operations are

called:

DDSDomainParticipantFactory::create participant (p. 1233)

DDSDomainParticipantFactory::create participant with proﬁle

(p. 1235)

DDSDomainParticipantFactory::set default participant qos -

with proﬁle (p. 1223)

DDSDomainParticipantFactory::get default participant qos

(p. 1224)

DDSDomainParticipantFactory::set default library (p. 1225)

DDSDomainParticipantFactory::set default proﬁle (p. 1225)

DDSDomainParticipantFactory::get participant qos from -

proﬁle (p. 1227)

DDSDomainParticipantFactory::get topic qos from proﬁle

(p. 1231)

DDSDomainParticipantFactory::get topic qos from proﬁle w -

topic name (p. 1232)

DDSDomainParticipantFactory::get publisher qos from proﬁle

(p. 1228)

DDSDomainParticipantFactory::get subscriber qos from proﬁle

(p. 1228)

DDSDomainParticipantFactory::get datawriter qos from -

proﬁle (p. 1229)

DDSDomainParticipantFactory::get datawriter qos from -

proﬁle w topic name (p. 1229)

DDSDomainParticipantFactory::get datareader qos from -

proﬁle (p. 1230)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

152 Module Documentation

DDSDomainParticipantFactory::get datareader qos from -

proﬁle w topic name (p. 1231)

DDSDomainParticipantFactory::get qos proﬁle libraries

(p. 1233)

DDSDomainParticipantFactory::get qos proﬁles (p. 1233)

DDSDomainParticipantFactory::load proﬁles (p. 1238)

The QoS proﬁles are reloaded replacing previously loaded proﬁles when the

follow ing operations are called:

DDSDomainParticipantFactory::set qos (p. 1237)

DDSDomainParticipantFactory::reload proﬁles (p. 1238)

The DDSDomainParticipantFactory::unload proﬁles() (p. 1239) opera-

tion will free the resources associated with the XML QoS proﬁles.

There are ﬁve ways to conﬁgure the XML resources (listed by load order):

The ﬁle NDDS QOS PROFILES.xml in NDDSHOME/resource/qos -

proﬁles 5.0.0/xml is loaded if it exists and DDS -

ProﬁleQosPolicy::ignore resource proﬁle (p. 832) in DDS -

ProﬁleQosPolicy (p. 830) is set to DDS BOOLEAN FALSE (p. 299)

(ﬁrst to be loaded). An example ﬁle, NDDS QOS PROFILES.example.xml,

is available for reference.

The URL groups separated by semicolons referenced by the enviroment

variable NDDS QOS PROFILES are loaded if they exist and DDS -

ProﬁleQosPolicy::ignore environment proﬁle (p. 831) in DDS -

ProﬁleQosPolicy (p. 830) is set to DDS BOOLEAN FALSE (p. 299).

The ﬁle USER QOS PROFILES.xml in the working directory will

be loaded if it exists and DDS ProﬁleQosPolicy::ignore user -

proﬁle (p. 831) in DDS ProﬁleQosPolicy (p. 830) is set to DDS -

BOOLEAN FALSE (p. 299).

The URL groups referenced by DDS ProﬁleQosPolicy::url proﬁle

(p. 831) in DDS ProﬁleQosPolicy (p. 830) will be loaded if speciﬁed.

The sequence of XML strings referenced by DDS -

ProﬁleQosPolicy::string proﬁle (p. 831) will be loaded if speciﬁed

(last to be loaded).

The above methods can be combined together.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.35 Conﬁguring QoS Proﬁles with XML 153

5.35.2 URL

The location of the XML resources (only ﬁles and strings are supported) is

speciﬁed using a URL (Uniform Resource Locator) format. For example:

File Speciﬁcation: file:///usr/local/default dds.xml

String Speciﬁcation: str://”<dds><qos library> . . . lt;/qos -

library>&lt/dds>”

If the URL schema name is omitted, RTI Connext will assume a ﬁle name. For

example:

File Speciﬁcation: /usr/local/default dds.xml

5.35.2.1 URL groups

To provide redundancy and fault tolerance, you can specify multiple locations

for a single XML document via URL groups. The syntax of a URL group is as

follows :

[URL1 | URL2 | URL2 | . . .| URLn]

For example:

[file:///usr/local/default dds.xml | file:///usr/local/alternative -

default dds.xml]

Only one of the elements in the group will be loaded by RTI Connext, starting

from the left.

Brackets are not required for groups with a single URL.

5.35.2.2 NDDS QOS PROFILES environment variable

The environment variable NDDS QOS PROFILES contains a list of URL

groups s eparated by ’;’

The URL groups referenced by the environment variable are loaded if they exist

and DDS ProﬁleQosPolicy::ignore environment proﬁle (p. 831) is set to

DDS BOOLEAN FALSE (p. 299)

For more information on XML Conﬁguration, refer to the User’s Manual.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

154 Module Documentation

5.36 Publication Example

A data publication example.

5.36.1 A typical publication example

Prep

Create user data types using rtiddsgen (p. 220)

Set up

Get the factory (p. 156)

Set up participant (p. 156)

Set up publisher (p. 165)

Set up topic(s) (p. 159)

Set up data writer(s) (p. 166)

Adjust the desired quality of service (QoS)

Adjust QoS on entities as necessary (p. 176)

Send data

Send data (p. 167)

Tear down

Tear down data writer(s) (p. 167)

Tear down topic(s) (p. 160)

Tear down publisher (p. 165)

Tear down participant (p. 157)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.37 Subscription Example 155

5.37 Subscription Example

A data subscription example.

5.37.1 A typical subscription example

Prep

Create user data types using rtiddsgen (p. 220)

Set up

Get the factory (p. 156)

Set up participant (p. 156)

Set up subscriber (p. 168)

Set up topic(s) (p. 159)

Set up data reader(s) (p. 172)

Set up data reader (p. 173) OR Set up subscriber (p. 168) to receive

data

Adjust the desired quality of service (QoS)

Adjust QoS on entities as necessary (p. 176)

Receive data

Access received data either via a reader (p. 173) OR via a subscriber

(p. 169) (possibly in a ordered or coherent (p. 170) manner)

Tear down

Tear down data reader(s) (p. 175)

Tear down topic(s) (p. 160)

Tear down subscriber (p. 170)

Tear down participant (p. 157)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

156 Module Documentation

5.38 Participant Use Cases

Working with domain partcipants. Working with domain participants.

5.38.1 Turning oﬀ auto-enable of newly created partici-

pant(s)

Get the factory (p. 156)

Change the value of the ENTITY FACTORY (p. 377) for the DDS-

DomainParticipantFactory (p. 1216)

DDS_DomainParticipantFactoryQos factory_qos;

if (factory->get_qos(factory_qos) != DDS_RETCODE_OK) {

printf("***Error: failed to get domain participant f acto ry qos\n");

}

/* Change the QosPolicy t o create disabled participants */

factory_qos.entity_factory.autoenable_created_entities = DDS_BOOLEAN_FALSE;

if (factory->set_qos(factory_qos) != DDS_RETCODE_OK) {

printf("***Error: failed to set domain participant f acto ry qos\n");

}

5.38.2 Getting the factory

Get the DDSDomainParticipantFactory (p. 1216) instance:

DDSDomainParticipantFactory* factory = NULL;

factory = DDSDomainParticipantFactory::get_instance();

if (factory == NULL) {

// ... error

}

5.38.3 Setting up a participant

Get the factory (p. 156)

Create DDSDomainParticipant (p. 1139):

DDS_DomainParticipantQos participant_qos;

DDSDomainParticipantListener* participant_listener = NULL;

DDS_ReturnCode_t retcode;

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.38 Participant Use Cases 157

// Set the initial peers. This list includes all the computers the

// application may communicate with, along with the maximum number of

// RTI Data Distribution Service participants that can concurrently

// run on that computer. This list only needs to be a superset of the

// actual list of compute rs and participants that will be running at

// any time.

const char* NDDS_DISCOVERY_INITIAL_PEERS[] = {

"host1",

"10.10.30.192",

"1@localhost",

"2@host2",

"my://", /* all unicast a ddrs on transport plugins with alias "my" */

"2@shmem://", /* shared memory */

"FF00:ABCD::0",

"sf://0/0/R", /* StarFabric transport plugin */

"1@FF00:0:1234::0",

"225.1.2.3",

"[email protected]",

"FAA0::0#0/0/R",

};

const DDS_Long NDDS_DISCOVERY_INITIAL_PEERS_LENGTH =

sizeof(NDDS_DISCOVERY_INITIAL_PEERS)/sizeof(const char*);

// initialize participant_qos with default values

retcode = factory->get_default_participant_qos(participant_qos);

if (retcode != DDS_RETCODE_OK) {

printf("***Error: failed to get default participant qos\n");

}

if (!participant_qos.discovery.initial_peers.from_array(

NDDS_DISCOVERY_INITIAL_PEERS,

NDDS_DISCOVERY_INITIAL_PEERS_LENGTH)) {

printf("***Error: failed to set discovery.initial_peers qos\n");

}

// Create the participant

DDSDomainParticipant* participant =

factory->create_participant(domain_id,

participant_qos,

participant_listener,

DDS_STATUS_MASK_NONE);

if (participant == NULL) {

printf("***Error: failed to create domain participant\n");

};

return participant;

5.38.4 Tearing down a participant

Get the factory (p. 156)

Delete DDSDomainParticipant (p. 1139):

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

158 Module Documentation

DDS_ReturnCode_t retcode;

retcode = factory->delete_participant(participant);

if (retcode != DDS_RETCODE_OK) {

// ... check for cause of failure

}

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.39 Topic Use Cases 159

5.39 Topic Use Cases

Working with topics.

5.39.1 Registering a user data type

Set up participant (p. 156)

const char* type_name = " My_T ype" ;

DDS_ReturnCode_t retcode;

retcode = FooTypeSupport::register_type(participant, type_name);

if (retcode != DDS_RETCODE_OK) {

// ... error

}

5.39.2 Setting up a topic

Set up participant (p. 156)

Ensure user data type is registered (p. 159)

Create a DDSTopic (p. 1419) under the name ”my topic”

const char* topic_name = "my_topic";

const char* type_type = " My_T ype" ; // user data type

DDS_TopicQos topic_qos;

DDS_ReturnCode_t retcode;

// MyTopicListener is user defined and

// extends DDSTopicListener

DDSTopicListener* topic_listener = new MyTopicListener(); // or = NULL

retcode = participant->get_default_topic_qos(topic_qos);

if (retcode != DDS_RETCODE_OK) {

// ... error

}

DDSTopic* topic = participant->create_topic(topic_name, type_name,

topic_qos, topic_listener,

DDS_STATUS_MASK_ALL);

if (topic == NULL) {

// ... error

};

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

160 Module Documentation

5.39.3 Tearing down a topic

Delete DDSTopic (p. 1419):

DDS_ReturnCode_t retcode;

retcode = participant->delete_topic(topic);

if (retcode != DDS_RETCODE_OK) {

// ... check for cause of failure

}

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.40 FlowController Use Cases 161

5.40 FlowController Use Cases

Working with ﬂow controllers.

5.40.1 Creating a ﬂow controller

Set up participant (p. 156)

Create a ﬂow controller

DDS_ReturnCode_t retcode;

DDSFlowController *controller = NULL;

DDS_FlowControllerProperty_t property;

retcode = participant->get_default_flowcontroller_property(property);

if (retcode != DDS_RETCODE_OK) {

printf("***Error: failed to get default flow control ler property\n");

}

// optionally modify flow controller property values

controller = participant->create_flowcontroller(

"my flow controller name", property);

if (controller == NULL) {

printf("***Error: failed to create flow controller\n");

}

5.40.2 Flow controlling a data writer

Set up participant (p. 156)

Create ﬂow controller (p. 161)

Create an asynchronous data writer, FooDataWriter (p. 1475), of user

data type Foo (p. 1443):

DDS_DataWriterQos writer_qos;

DDS_ReturnCode_t retcode;

// MyWriterListener is user defined and

// extends DDSDataWriterListener

MyWriterListener* writer_listener = new MyWriterListener(); // or = NULL

retcode = publisher->get_default_datawriter_qos(writer_qos);

if (retcode != DDS_RETCODE_OK) {

// ... error

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

162 Module Documentation

}

/* Change the writer QoS to publish asnychronously */

writer_qos.publish_mode.kind = DDS_ASYNCHRONOUS_PUBLISH_MODE_QOS;

/* Setup to use the previously created flow controller */

writer_qos.publish_mode.flow_controller_name =

DDS_String_dup("my flow controller name");

/* Samples queued for asy nchr onou s write are subject to the History Qos policy */

writer_qos.history.kind = DDS_KEEP_ALL_HISTORY_QOS;

FooDataWriter* writer = publisher->create_datawriter(topic,

writer_qos,

writer_listener,

DDS_STATUS_MASK_ALL);

if (writer == NULL) {

// ... error

};

/* Send data asynchronously... */

/* Wait for asynchronous send completes, if desired */

retcode = writer->wait_for_asynchronous_publishing(timout);

if (retcode != DDS_RETCODE_OK) {

printf("***Error: failed to wait for asynchronous pu blis hin g\n" );

}

5.40.3 Using the built-in ﬂow controllers

RTI Connext provides several built-in ﬂow controllers.

The DDS DEFAULT FLOW CONTROLLER NAME (p. 91) built-

in ﬂow controller provides the basic asynchronous writer behavior.

When calling FooDataWriter::write (p. 1484), the call signals the

DDSPublisher (p. 1346) asynchronous publishing thread (DDS -

PublisherQos::asynchronous publisher (p. 852)) to send the actual

data. As with any DDS ASYNCHRONOUS PUBLISH MODE QOS

(p. 422) DDSDataWriter (p. 1113), the FooDataWriter::write (p. 1484)

call returns immediately afterwards. The data is sent immediately in the

context of the DDSPublisher (p. 1346) asynchronous publishing thread.

When using the DDS FIXED RATE FLOW CONTROLLER NAME

(p. 92) ﬂow controller, data is also sent in the context of the DDSPub-

lisher (p. 1346) asynchronous publishing thread, but at a regular ﬁxed in-

terval. The thread accumulates samples from diﬀerent DDSDataWriter

(p. 1113) instances and generates data on the wire only once per DDS -

FlowControllerTokenBucketProperty t::period (p. 753).

In contrast, the DDS ON DEMAND FLOW CONTROLLER NAME

(p. 93) ﬂow controller permits ﬂow only when DDSFlowController::trigger -

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.40 FlowController Use Cases 163

ﬂow (p. 1261) is called. The data is still sent in the context of the DDSPub-

lisher (p. 1346) asynchronous publishing thread. The thread accumulates sam -

ples from diﬀerent DDSDataWriter (p. 1113) instances (ac ross any DDSPub-

lisher (p. 1346)) and sends all data since the previous trigger.

The prop e rties of the built-in DDSFlowController (p. 1259) instances can be

adjusted.

Set up participant (p. 156)

Lookup built-in ﬂow controller

DDSFlowController *controller = NULL;

controller = participant->lookup_flowcontroller(

DDS_DEFAULT_FLOW_CONTROLLER_NAME);

/* This should never happ en, built-in flow controllers are always created */

if (controller == NULL) {

printf("***Error: failed to lookup flow controller\n");

}

Change property of built-in ﬂow controller, if desired

DDS_ReturnCode_t retcode;

DDS_FlowControllerProperty_t property;

/* Get the property of the flow controller */

retcode = controller->get_property(property);

if (retcode != DDS_RETCODE_OK) {

printf("***Error: failed to get flow controller prop ert y\n" );

}

/* Change the property va lue as desired */

property.token_bucket.period.sec = 2;

property.token_bucket.period.nanosec = 0;

/* Update the flow contro ller property */

retcode = controller->set_property(property);

if (retcode != DDS_RETCODE_OK) {

printf("***Error: failed to set flow controller prop ert y\n" );

}

Create a data writer using the correct ﬂow controller name

(p. 161)

5.40.4 Shaping the network traﬃc for a particular trans-

port

Set up participant (p. 156)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

164 Module Documentation

Create the transports (p. 181)

Create a separate ﬂow controller for each transport (p. 161)

Conﬁgure DDSDataWriter (p. 1113) instances to only use a single trans-

port

Associate all data writers using the same transp ort to the cor-

responding ﬂow controller (p. 161)

For each transport, the corresponding ﬂow controller limits the network

traﬃc based on the token bucket properties

5.40.5 Coalescing multiple samples in a single network

packet

Set up participant (p. 156)

Create a ﬂow controller with a desired token bucket period

(p. 161)

Associate the data writer with the ﬂow controller (p. 161)

Multiple samples written within the spec iﬁed period will be coalesced

into a single network packet (provided that tokens added per period

and bytes per token permit).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.41 Publisher Use Cases 165

5.41 Publisher Use Cases

Working with publishers.

5.41.1 Setting up a publisher

Set up participant (p. 156)

Create a DDSPublisher (p. 1346)

DDS_PublisherQos publisher_qos;

// MyPublisherListener is user defined and

// extends DDSPublisherListener

DDSPublisherListener* publisher_listener =

= new MyPublisherListener(); // or = NULL

participant->get_default_publisher_qos(publisher_qos);

DDSPublisher* publisher = participant->create_publisher(publisher_qos,

publisher_listener,

DDS_STATUS_MASK_ALL);

if (publisher == NULL) {

// ... error

};

5.41.2 Tearing down a publisher

Delete DDSPublisher (p. 1346):

DDS_ReturnCode_t retcode;

retcode = participant->delete_publisher(publisher);

if (retcode != DDS_RETCODE_OK) {

// ... check for cause of failure

}

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

166 Module Documentation

5.42 DataWriter Use Cases

Working with data writers.

5.42.1 Setting up a data writer

Set up publisher (p. 165)

Set up a topic (p. 159)

Create a data writer, FooDataWriter (p. 1475), of user data type Foo

(p. 1443):

DDS_DataWriterQos writer_qos;

DDS_ReturnCode_t retcode;

// MyWriterListener is user defined and

// extends DDSDataWriterListener

MyWriterListener* writer_listener = new MyWriterListener(); // or = NULL

retcode = publisher->get_default_datawriter_qos(writer_qos);

if (retcode != DDS_RETCODE_OK) {

// ... error

}

FooDataWriter* writer = publisher->create_datawriter(topic,

writer_qos,

writer_listener,

DDS_STATUS_MASK_ALL);

if (writer == NULL) {

// ... error

};

5.42.2 Managing instances

Getting an instance ”key” value of user data type Foo (p. 1443)

Foo* data = ...; // user data

retcode = writer->get_key_value(*data, instance_handle);

if (retcode != DDS_RETCODE_OK) {

// ... check for cause of failure

}

Registering an instance of type Foo (p. 1443)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.42 DataWriter Use Cases 167

DDS_InstanceHandle_t instance_handle = DDS_HANDLE_NIL;

instance_handle = writer->register_instance(data);

Unregistering an instance of type Foo (p. 1443)

retcode = writer->unregister_instance(data, instance_handle);

if (retcode != DDS_RETCODE_OK) {

// ... check for cause of failure

}

Disposing of an instance of type Foo (p. 1443)

retcode = writer->dispose(data, instance_handle);

if (retcode != DDS_RETCODE_OK) {

// ... check for cause of failure

}

5.42.3 Sending data

Set up data writer (p. 166)

Write instance of type Foo (p. 1443)

Foo* data; // user data

DDS_InstanceHandle_t instance_handle =

DDS_HANDLE_NIL; // or a v alid registered handle

DDS_ReturnCode_t retcode;

retcode = writer->write(data, instance_handle);

if (retcode != DDS_RETCODE_OK) {

// ... check for cause of failure

}

5.42.4 Tearing down a data writer

Delete DDSDataWriter (p. 1113):

DDS_ReturnCode_t retcode;

retcode = publisher->delete_datawriter(writer);

if (retcode != DDS_RETCODE_OK) {

// ... check for cause of failure

}

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

168 Module Documentation

5.43 Subscriber Use Cases

Working with subscribe rs.

5.43.1 Setting up a subscriber

Set up participant (p. 156)

Create a DDSSubscriber (p. 1390)

DDS_SubscriberQos subscriber_qos;

DDS_ReturnCode_t retcode;

// MySubscriberListener is user defined and

// extends DDSSubscriberListener

DDSSubscriberListener* subscriber_listener =

new MySubscriberListener(); // or = NULL

retcode = participant->get_default_subscriber_qos(subscriber_qos);

if (retcode != DDS_RETCODE_OK) {

// ... error

};

DDSSubscriber* subscriber =

participant->create_subscriber(subscriber_qos,

subscriber_listener,

DDS_STATUS_MASK_ALL);

if (subscriber == NULL) {

// ... error

};

5.43.2 Set up subscriber to access received data

Set up subscriber (p. 168)

Set up to handle the DDS DATA ON READERS STATUS status, in one

or both of the following two ways.

Enable DDS DATA ON READERS STATUS for the DDSSub-

scriberListener associated with the subscriber (p. 177)

– The processing to handle the status change is done in the DDSSub-

scriberListener::on data on readers() (p. 1415) metho d of the

attached listener.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.43 Subscriber Use Cases 169

– Typical processing will access the received data (p. 169), either in

arbitrary order or in a coherent and ordered manner (p. 170).

Enable DDS DATA ON READERS STATUS for the DDSSta-

tusCondition associated with the subscriber (p. 178)

– The processing to handle the status change is done when the sub-

scriber’s attached status condition is triggered (p. 179) and

the DDS DATA ON READERS STATUS status on the subscriber

is changed.

– Typical processing will access the received data (p. 169), either in

an arbitrary order or in a coherent and ordered manner (p. 170).

5.43.3 Access received data via a subscriber

Ensure subscriber is set up to access received data (p. 168)

Get the list of readers that have data samples available:

DDSDataReaderSeq reader_seq; // holder for list/set of readers

DDS_SampleStateMask sample_state_mask = DDS_NOT_READ_SAMPLE_STATE;

DDS_ViewStateMask view_state_mask = DDS_ANY_VIEW_STATE;

DDS_InstanceStateMask i nsta nce_ sta te_m ask = DDS_ANY_INSTANCE_STATE;

DDS_ReturnCode_t retcode;

// get_datareadersX is not supported yet.

retcode = subscriber->get_datareaders(reader_seq,

sample_state_mask,

view_state_mask,

instance_state_mask);

if (retcode != DDS_RETCODE_OK) {

// ... check for cause of failure

}

Upon successfully getting the list of readers with data, process the data

readers to either:

– Read the data in each reader (p. 174), OR

– Take the data in each reader (p. 173)

If the intent is to access the data coherently or in order (p. 170), the

list of data readers must be processed in the order returned:

for(int i = 0; i < reader_seq.length(); ++i) {

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

170 Module Documentation

TDataReader* reader = reader_seq[i];

// Take the data from reader,

// OR

// Read the data from reader

}

Alternatively, call DDSSubscriber::notify datareaders() (p. 1408)

to invoke the DDSDataReaderListener (p. 1108) for each of the data

readers.

retcode = subscriber->notify_datareaders();

if (retcode != DDS_RETCODE_OK) {

// ... check for cause of failure

}

5.43.4 Access received data coherently and/or in order

To access the received data coherently and/or in an ordered manner, according

to the settings of the DDS Presentat ionQosPolicy (p. 823) attached to a

DDSSubscriber (p. 1390):

Ensure subscriber is set up to access received data (p. 168)

Indicate that data will be accessed via the subscriber:

retcode = subscriber->begin_access();

if (retcode != DDS_RETCODE_OK) {

// ... check for cause of failure

}

Access received data via the subscriber, making sure that the

data readers are processed in the order returned. (p. 169)

Indicate that the data access via the subscriber is done:

retcode = subscriber->end_access();

if (retcode != DDS_RETCODE_OK) {

// ... check for cause of failure

}

5.43.5 Tearing down a subscriber

Delete DDSSubscriber (p. 1390):

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.43 Subscriber Use Cases 171

DDS_ReturnCode_t retcode;

retcode = participant->delete_subscriber(subscriber);

if (retcode != DDS_RETCODE_OK) {

// ... check for cause of failure

}

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

172 Module Documentation

5.44 DataReader Use Cases

Working with data readers.

5.44.1 Setting up a data reader

Set up subscriber (p. 168)

Set up a topic (p. 159)

Create a data reader, FooDataReader (p. 1444), of user data type Foo

(p. 1443):

DDS_DataReaderQos reader_qos;

DDS_ReturnCode_t retcode;

// MyReaderListener is user defined and

// extends DDSDataReaderListener

DDSDataReaderListener* reader_listener =

new MyReaderListener(); // or = NULL

retcode = subscriber->get_default_datareader_qos(reader_qos);

if (retcode != DDS_RETCODE_OK) {

// ... error

};

FooDataReader* reader = subscriber->create_datareader(topic,

reader_qos,

reader_listener,

DDS_STATUS_MASK_ALL);

if (reader == NULL) {

// ... error

};

5.44.2 Managing instances

Give n a data reader

FooDataReader* reader = ...;

Getting an instance ”key” value of user data type Foo (p. 1443)

Foo data; // user data of type Foo

// ...

retcode = reader->get_key_value(data, instance_handle);

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.44 DataReader Use Cases 173

if (retcode != DDS_RETCODE_OK) {

// ... check for cause of failure

}

5.44.3 Set up reader to access received data

Set up data reader (p. 172)

Set up to handle the DDS DATA AVAILABLE STATUS status, in one or

both of the following two ways.

Enable DDS DATA AVAILABLE STATUS for the DDS-

DataReaderListener associated with the data reader (p. 177)

– The processing to handle the status change is done in the DDS-

DataReaderListener::on data available (p. 1110) method of the

attached listener.

– Typical processing will access the received data (p. 173).

Enable DDS DATA AVAILABLE STATUS for the DDSStatus-

Condition associated with the data reader (p. 178)

– The processing to handle the status change is done when the data

reader’s attached status condition is triggered (p. 179) and

the DDS DATA AVAILABLE STATUS status on the data reader is

changed.

– Typical processing will access the received data (p. 173).

5.44.4 Access received data via a reader

Ensure reader is set up to access received data (p. 173)

Access the received data, by either:

– Taking the received data in the reader (p. 173), OR

– Reading the received data in the reader (p. 174)

5.44.5 Taking data

Ensure reader is set up to access received data (p. 173)

Take samples of user data type T. The samples are removed from the

Service. The caller is responsible for deallocating the buﬀers.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

174 Module Documentation

FooSeq data_seq; // holder for sequence of user data type Foo

DDS_SampleInfoSeq info_seq; // holde r for sequence of DDS_SampleInfo

long max_samples = DDS_LENGTH_UNLIMITED;

DDS_SampleStateMask sam ple_ stat e_m ask = DDS_ANY_SAMPLE_STATE;

DDS_ViewStateMask view_state_mask = DDS_ANY_VIEW_STATE;

DDS_InstanceStateMask instance_state_mask = DDS_ANY_INSTANCE_STATE;

DDS_ReturnCode_t retcode;

retcode = reader->take(data_seq, info_seq,

max_samples,

sample_state_mask,

view_state_mask,

instance_state_mask);

if (retcode == DDS_RETCODE_NO_DATA) {

return;

} else if (retcode != DDS_RETCODE_OK) {

// ... check for cause of failure

}

Use the received data

// Use the received data samples ’data_seq’ and associated information ’info_seq’

for(int i = 0; i < data_seq.length(); ++i) {

// use... data_seq[i] ...

// use... info_seq[i] ...

}

Return the data samples and the information buﬀers back to the mid-

dleware. IMPORTANT : Once this call returns, you must not retain any

pointers to any part of any sample or sample info object.

retcode = reader->return_loan(data_seq, info_seq);

if (retcode != DDS_RETCODE_OK) {

// ... check for cause of failure

}

5.44.6 Reading data

Ensure reader is set up to access received data (p. 173)

Read samples of user data type Foo (p. 1443). The samples are not

removed from the Service. It rem ains responsible for deallocating the

buﬀers.

FooSeq data_seq; // holder for sequence of user data type Foo

DDS_SampleInfoSeq info_seq; // holder for sequ ence of DDS_SampleInfo

long max_samples = DDS_LENGTH_UNLIMITED;

DDS_SampleStateMask sam ple_ stat e_m ask = DDS_NOT_READ_SAMPLE_STATE ;

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.44 DataReader Use Cases 175

DDS_ViewStateMask view_state_mask = DDS_ANY_VIEW_STATE;

DDS_InstanceStateMask instance_state_mask = DDS_ANY_INSTANCE_STATE;

DDS_ReturnCode_t retcode;

retcode = reader->read(data_seq, info_seq,

max_samples,

sample_state_mask,

view_state_mask,

instance_state_mask);

if (retcode == DDS_RETCODE_NO_DATA) {

return;

} else if (retcode != DDS_RETCODE_OK) {

// ... check for cause of failure

}

Use the received data

// Use the received data samples ’data_seq’ and associated

// information ’info_seq’

for(int i = 0; i < data_seq.length(); ++i) {

// use... data_seq[i] ...

// use... info_seq[i] ...

}

Return the data samples and the information buﬀers back to the middle-

ware

retcode = reader->return_loan(data_seq, info_seq);

if (retcode != DDS_RETCODE_OK) {

// ... check for cause of failure

}

5.44.7 Tearing down a data reader

Delete DDSDataReader (p. 1087):

DDS_ReturnCode_t retcode;

retcode = subscriber->delete_datareader(reader);

if (retcode != DDS_RETCODE_OK) {

// ... check for cause of failure

}

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

176 Module Documentation

5.45 Entity Use Cases

Working with entities.

5.45.1 Enabling an entity

To enable an DDSEnti ty (p. 1253)

if (entity->enable() != DDS_RETCODE_OK) {

printf("***Error: failed to enable entity\n");

}

5.45.2 Checking if a status changed on an entity.

Give n an DDSEntity (p. 1253) and a DDS StatusKind (p. 322) to

check for, get the list of statuses that have changed since the last time

they were respectively cleared.

DDS_StatusMask status_changes_mask = entity->get_status_changes();

Check if status kind was changed since the last time it was cleared.

A plain communication status change is cleared when the status is read

using the entity’s get <plain communication status>() method. A

read communication status change is cleared when the data is taken from

the middleware via a TDataReader take() call [see Changes in Status

(p. 319) for details].

if (status_changes_mask & status_kind) {

return true;

} else { /* ... YES, status_kind changed ... */

return false; /* ... NO, status_kind did NOT change ... */

}

5.45.3 Changing the QoS for an entity

The QoS for an entity can be speciﬁed at the entity creation time. Once an

entity has been created, its QoS can be manipulated as follows.

Get an entity’s QoS settings using get qos (abstract) (p. 1255)

if (entity->get_qos(qos) != DDS_RETCODE_OK) {

printf("***Error: failed to get qos\n");

}

Change the desired qos policy ﬁelds

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.45 Entity Use Cases 177

/* Change the desired qos policies */

/* qos.policy.field = ... */

Set the qos using set qos (abstract) (p. 1254).

switch (entity->set_qos(qos)) {

case DDS_RETCODE_OK: { /* success */

} break;

case DDS_RETCODE_IMMUTABLE_POLICY: {

printf("***Error: tried changing a policy that can only be"

" set at entity creation ti me\n ");

} break;

case DDS_RETCODE_INCONSISTENT_POLICY: {

printf("***Error: tried changing a policy to a value inconsistent"

" with other policy settings\n");

} break;

default: {

printf("***Error: some other failure\n");

}

5.45.4 Changing the listener and enabling/disabling sta-

tuses associated with it

The listener for an entity can be speciﬁed at the entity creation time. By default

the listener is enabled for all the statuses supported by the entity.

Once an entity has been created, its listener and/or the statuses for which it is

enabled can be manipulated as follows.

User deﬁnes entity listener methods

/* ... methods defined by EntityListener ... */

public class MyEntityListener implements DDSListener {

// ... methods defined by EntityListener ...

}

Get an entity’s listener using get listener (abstract) (p. 1256)

entity_listener = entity->get_listener();

Enable status kind for the listener

enabled_status_list |= status_kind;

Disable status kind for the listener

enabled_status_list &= ~status_kind;

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

178 Module Documentation

Set an entity’s listener to entity listener using set listener (ab-

stract) (p. 1255). Only enable the listener for the statuses speciﬁed by

the enabled status list.

if (entity->set_listener(entity_listener, enabled_status_list)

!= DDS_RETCODE_OK) {

printf("***Error: setting entity listener\n");

}

5.45.5 Enabling/Disabling statuses associated with a sta-

tus condition

Upon entity creation, by default, all the statuses are enabled for the DDS

StatusCondition associated with the entity.

Once an entity has been created, the list of statuses for which the DDS -

StatusCondition is triggered can be manipulated as follows.

Give n an entity, a status kind, and the associated status condition:

statuscondition = entity->get_statuscondition();

Get the list of statuses enabled for the status condition

enabled_status_list = statuscondition->get_enabled_statuses();

Check if the given status kind is enabled for the status condition

if (enabled_status_list & status_kind) {

/*... YES, status_kind is enabled ... */

} else {

/* ... NO, status_kind is NOT enabled ... */

}

Enable status kind for the status condition

if (statuscondition->set_enabled_statuses(enabled_status_li st | status_kind)

!= DDS_RETCODE_OK) {

/* ... check for cause of failure */

}

Disable status kind for the status condition

if (statuscondition->set_enabled_statuses(enabled_status_li st & ~status_kind)

!= DDS_RETCODE_OK) {

/* ... check for cause of failure */

}

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.46 Waitset Use Cases 179

5.46 Waitset Use Cases

Using wait-sets and conditions.

5.46.1 Setting up a wait-set

Create a wait-set

DDSWaitSet* waitset = new DDSWaitSet();

Attach conditions

DDSCondition* cond1 = ...;

DDSCondition* cond2 = entity->get_statuscondition();

DDSCondition* cond3 = reader->create_readcondition(DDS_NOT_READ_SAMPLE_STATE,

DDS_ANY_VIEW_STATE,

DDS_ANY_INSTANCE_STATE);

DDSCondition* cond4 = new DDSGuardCondition();

DDSCondition* cond5 = ...;

DDS_ReturnCode_t retcode;

retcode = waitset->attach_condition(cond1);

if (retcode != DDS_RETCODE_OK) {

// ... error

}

retcode = waitset->attach_condition(cond2);

if (retcode != DDS_RETCODE_OK) {

// ... error

}

retcode = waitset->attach_condition(cond3);

if (retcode != DDS_RETCODE_OK) {

// ... error

}

retcode = waitset->attach_condition(cond4);

if (retcode != DDS_RETCODE_OK) {

// ... error

}

retcode = waitset->attach_condition(cond5);

if (retcode != DDS_RETCODE_OK) {

// ... error

}

5.46.2 Waiting for condition(s) to trigger

Set up a wai t-set (p. 179)

Wait for a c ondition to trigger or timeout, whichever occurs ﬁrst

DDS_Duration_t timeout = { 0, 1000000 }; // 1ms

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

180 Module Documentation

DDSConditionSeq active_conditions; // holder for active conditions

bool is_cond1_triggered = false;

bool is_cond2_triggered = false;

DDS_ReturnCode_t retcode;

retcode = waitset->wait(active_conditions, timeout);

if (retcode != DDS_RETCODE_OK) {

if (retcode == DDS_RETCODE_TIMEOUT) {

// Timeout

} else {

// Failure

} else {

// success, check if "con d1" or "cond2" are triggered:

for(int i = 0; i < active_conditions.length(); ++i) {

if (active_conditions[i] == cond1) {

printf("Cond1 was triggered!");

is_cond1_triggered = true;

}

if (active_conditions[i] == cond2) {

printf("Cond2 was triggered!");

is_cond2_triggered = true;

}

if (is_cond1_triggered && is_cond2_triggered) {

break;

}

if (is_cond1_triggered) {

// ... do something becau se "cond1" was triggered ...

}

if (is_cond2_triggered) {

// ... do something becau se "cond2" was triggered ...

}

return retcode;

5.46.3 Tearing down a wait-set

Delete the wait-set

delete waitset;

waitset = NULL;

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.47 Transport Use Cases 181

5.47 Transport Use Cases

Working with pluggable transports.

5.47.1 Changing the automatically registered built-in

transports

The DDS TRANSPORTBUILTIN MASK DEFAULT (p. 397)

speciﬁes the transport plugins that will be automatically registered with

a newly created DDSDomainParticipant (p. 1139) by default.

This default can be changed by changing the value of the value of

TRANSPORT BUILTIN (p. 396) Qos Policy on the DDSDomain-

Participant (p. 1139)

To change the DDS DomainParticipantQos::transport builtin

(p. 590) Qos Policy:

DDS_DomainParticipantQos participant_qos;

factory->get_default_participant_qos(participant_qos);

participant_qos.transport_builtin.mask = DDS_TRANSPORTBUILTIN_SHMEM |

DDS_TRANSPORTBUILTIN_UDPv4;

5.47.2 Changing the properties of the automatically reg-

istered builtin transports

The behavior of the automatically registered builtin transports can be altered

by changing their properties.

Tell the DDSDomainParticipantFactory (p. 1216) to create the par-

ticipants disabled, as described in Turning oﬀ auto-enable of newly

created participant(s) (p. 156)

Get the property of the desired builtin transport plugin, say ::UDPv4

Transport (p. 265)

struct NDDS_Transport_UDPv4_Property_t property = NDDS_TRANSPORT_UDPV4_PROPERTY_DEFAULT;

if (NDDSTransportSupport::get_builtin_transport_property(

participant,

DDS_TRANSPORTBUILTIN_UDPv4,

(struct NDDS_Transport_Property_t&)property)

!= DDS_RETCODE_OK) {

printf("***Error: get builtin transport property\n");

}

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

182 Module Documentation

Change the property ﬁelds as desired. Note that the properties should

be changed carefully, as inappropriate values may prevent communica-

tions. For example, the ::UDPv4 Transport (p. 265) properties can be

changed to support large messages (assuming the underlying operating

system’s UDPv4 stack s upports the large message size). Note: if mes-

sage size max is increased from the default for any of the built-in trans-

ports, then the DDS ReceiverPoolQosPolicy::buﬀer size (p. 864) on

the DomainParticipant should also be changed.

/* Increase the UDPv4 max imum message size to 64K (large messages). */

property.parent.message_size_max = 65535;

property.recv_socket_buffer_size = 65535;

property.send_socket_buffer_size = 65535;

Set the property of the desired builtin transport plugin, say ::UDPv4

Transport (p. 265)

if (NDDSTransportSupport::set_builtin_transport_property(

participant,

DDS_TRANSPORTBUILTIN_UDPv4,

(struct NDDS_Transport_Property_t&)property)

!= DDS_RETCODE_OK) {

printf("***Error: set builtin transport property\n");

}

Enable the participant (p. 176) to turn on communications with other

participants in the domain using the new properties for the automatically

registered builtin transport plugins.

5.47.3 Creating a transport

A transport plugin is created using methods provided by the supplier of

the transport plugin.

For example to create an instance of the ::UDPv4 Transport (p. 265)

NDDS_Transport_Plugin* transport = NULL;

struct NDDS_Transport_UDPv4_Property_t property = NDDS_TRANSPORT_UDPV4_PROPERTY_DEFAULT;

transport = NDDS_Transport_UDPv4_new(&property);

if (transport == NULL) {

printf("***Error: creating transport plugin\n");

}

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.47 Transport Use Cases 183

5.47.4 Deleting a transport

A transport plugin can only be deleted only after the DDSDomainPar-

ticipant (p. 1139) with which it is registered is deleted.

The virtual destructor provided by the abstract transport plugin API can

be used to delete a transport plugin.

transport->delete_cEA(transport, NULL);

5.47.5 Registering a transport with a participant

The basic steps for setting up transport plugins for use in an RTI Connext

application are described below.

Tell the DDSDomainParticipantFactory (p. 1216) to create the par-

ticipants disabled, as described in Turning oﬀ auto-enable of newly

created participant(s) (p. 156)

Optionally Changing the automatically registered built-in transports (p. 181)

Optionally Changing the properties of the autom atical ly registered builtin

transports (p. 181)

Create a disabled DDSDomainParticipant (p. 1139), as described in

Setting up a participant (p. 156)

Decide on the network address (p. 128) for the transport plugin. The

network address should be chosen so that the resulting fully qualiﬁed ad-

dress is globally unique (across all transports used in the domain).

/* Decide on a network address (96 bits for UDPv4), such that the fully

qualified unicast address for the transport’s interf ace s will be

globally unique. For example, we use the network address:

1234:1234:1234:0000

It will be prepended to the unicast addresses of the transport plugin’s

interfaces, to give a ful ly qualified address that is unique in the

domain.

NDDS_Transport_Address_t network_address = {{1,2,3,4, 1,2,3,4, 1,2,3,4, 0,0,0,0}};

Decide on the aliases (p. 125) for the transport plugin. An alias can refer

to one or more transport plugins. The transport class name (see Builtin

Transport Class Names (p. 394)) are automatically appended to the

user-provided aliases. Alias names are useful in creating logical groupings

of transports, e.g. all the transports that are conﬁgured to support large

messages may be given the alias ”large message”.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

184 Module Documentation

/* Decide aliases, i.e. t he names by which this transport plugin will be kn own */

const char* ALIASES[] = {

"my",

"large_message",

};

const DDS_Long ALIASES_LENGTH = sizeof(ALIASES)/sizeof(const char*);

/* Initialize the aliases StringSeq */

DDS_StringSeq aliases;

if (!aliases.from_array(ALIASES, ALIASES_LENGTH)) {

printf("***Error: creating initializing aliases\n");

}

(p. 1139). Note that a transport plugin should NOT be registered with

more than one DomainParticipant. It is the responsibility of the ap-

plication programmer to ensure that this requirement is not violated.

NDDS_Transport_Handle_t handle = NDDS_TRANSPORT_HANDLE_NIL;

handle = NDDSTransportSupport::register_transport(

participant, /* Disabled Domain Participant */

transport, /* Transport plugin */

aliases, /* Transport aliases */

network_address); /* Transport netwo rk address */

if (NDDS_Transport_Handle_is_nil(&handle)) {

printf("***Error: registering transport\n");

}

Optionally Adding receive routes for a transport (p. 184)

Optionally Adding send routes for a transport (p. 185)

Enable the participant (p. 176) to turn on communications with other

participants in the domain, using the newly registered transport plugins,

and automatically registered builtin transport plugins (if any).

5.47.6 Adding receive routes for a transport

Receive routes can be added to restrict address ranges on which incoming

messages can be received. Any number of receive routes can be added,

but thes e must be done before the participant is enabled.

To restrict the address range from which incoming messages can be re-

ceived by the transport plugin:

/* Restrict to receiving messages only on interfaces

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.47 Transport Use Cases 185

1234:1234:1234:10.10.*.*

NDDS_Transport_Address_t subnet = {{1,2,3,4, 1,2,3,4, 1,2,3,4, 10,10,0,0}};

if (NDDSTransportSupport::add_receive_route(handle, subnet, 112)

!= DDS_RETCODE_OK) {

printf("***Error: adding receive route\n");

}

5.47.7 Adding send routes for a transport

Send routes can be added to restrict the address ranges to which outgoing

messages can be sent by the transport plugin. Any number of send routes

can be added, but these must be done before the participant is enabled.

To restrict address ranges to which outgoing messages can be se nt by the

transport plugin:

/* Restrict to sending me ssag es only to addresses (subnets)

1234:1234:1234:10.10.30.*

NDDS_Transport_Address_t subnet = {{1,2,3,4, 1,2,3,4, 1,2,3,4, 10,10,30,0}};

if (NDDSTransportSupport::add_send_route(handle, subnet, 120)

!= DDS_RETCODE_OK) {

printf("***Error: adding send route\n");

}

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

186 Module Documentation

5.48 Filter Use Cases

Working with data ﬁlters.

5.48.1 Introduction

RTI Connext supports ﬁltering data either during the exchange from DDS-

DataWriter (p. 1113) to DDSDataReader (p. 1087), or after the data has

been stored at the DDSDataReader (p. 1087).

Filtering during the exchange process is performed by a DDSContentFil-

teredTopic (p. 1081), which is created by the DDSDataReader (p. 1087) as

a way of specifying a subset of the data samples that it wishes to receive.

Filtering samples that have already been received by the DDSDataReader

(p. 1087) is performed by creating a DDSQueryCondition (p. 1372), which

can then used to check for matching samples, be alerted when match-

ing samples arrive, or retrieve matching samples through use of the

FooDataReader::read w condition (p. 1454) or FooDataReader::take -

w condition (p. 1456) functions. (Conditions may also be used with

the APIs FooDataReader::read next instance w condition (p. 1468) and

FooDataReader::take next instance w condition (p. 1470).)

Filtering may be performed on any topic, either ke yed or un-keyed, except

the Built-in Topics (p. 42). Filtering may be perfomed on any ﬁeld, s ubset

of ﬁelds, or combination of ﬁelds, subject only to the limitations of the ﬁlter

syntax, and some restrictions against ﬁltering some sparse value types of the

Dynamic Data (p. 77) API.

RTI Connext contains built in support for ﬁltering using SQL syntax, described

in the Queries and Filters Syntax (p. 208) module.

5.48.1.1 Overview of ContentFilteredTopic

Each DDSContentFilteredTopic (p. 1081) is created based on an exist-

ing DDSTopic (p. 1419). The DDSTopic (p. 1419) speciﬁes the ﬁeld -

names and ﬁeld types of the data contained within the topic. The

DDSContentFilteredTopic (p. 1081), by means of its filter expression

and expression parameters, futher speciﬁes the values of the data which the

DDSDataReader (p. 1087) wishes to receive.

Custom ﬁlters may also be constructed and utilized as described in the Creat-

ing Custom Content Filters (p. 191) module.

Once the DDSContentFilteredTopic (p. 1081) has been created, a DDS-

DataReader (p. 1087) can be created using the ﬁltered topic. The ﬁlter’s

characteristics are exchanged between the DDSDataReader (p. 1087) and any

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.48 Filter Use Cases 187

matching DDSDataWriter (p. 1113) during the discovery processs.

If the DDSDataWriter (p. 1113) allows (by DDS -

DataWriterResourceLimitsQosPolicy::max remote reader ﬁlters

(p. 562)) and the number of ﬁltered DDSDataReader (p. 1087) is less

than or equal to 32, and the DDSDataReader (p. 1087) ’s DDS -

TransportMulticastQosPoli cy (p. 978) is empty, then the DDS-

DataWriter (p. 1113) will performing ﬁltering and send to the DDS-

DataReader (p. 1087) only those samples that meet the ﬁltering c riteria.

If disallowed by the DDSDataWriter (p. 1113), or if more than 32 DDS-

DataReader (p. 1087) require ﬁltering, or the DDSDataReader (p. 1087)

has set the DDS TransportMulticastQosPolicy (p. 978), then the DDS-

DataWriter (p. 1113) sends all samples to the DDSDataReader (p. 1087),

and the DDSDataReader (p. 1087) discards any samples that do not meet

the ﬁltering criteria.

Although the filter expression cannot be changed once the DDSContent-

FilteredTopic (p. 1081) has been created, the expression parameters can be

modiﬁed using DDSContentFilteredTopic::set expression parameters

(p. 1084). Any changes made to the ﬁltering criteria by means of DDSCon-

tentFilteredTopic::set expression parameters (p. 1084), will be conveyed

to any connected DDSDataWriter (p. 1113). New samples will be subject to

the modiﬁed ﬁltering criteria, but samples that have already been accepted or

rejected are unaﬀected. However, if the DDSDataReader (p. 1087) connects

to a DDSDataWriter (p. 1113) that re-sends its data, the re-sent samples will

be subjected to the new ﬁltering criteria.

5.48.1.2 Overview of QueryCondition

DDSQueryCondition (p. 1372) combine aspects of the content ﬁltering ca-

pabilities of DDSContentFilteredTopic (p. 1081) with state ﬁltering capa-

bilities of DDSReadCondition (p. 1374) to create a reconﬁgurable means of

ﬁltering or searching data in the DDSDataReader (p. 1087) queue.

DDSQueryCondition (p. 1372) m ay be created on a disabled DDS-

DataReader (p. 1087), or after the DDSDataReader (p. 1087) has been en-

abled. If the DDSDataReader (p. 1087) is enabled, and has already recevied

and stored samples in its queue, then all data samples in the are ﬁltered against

the DDSQueryCondition (p. 1372) ﬁlter c riteria at the time that the DDS-

QueryCondition (p. 1372) is created. (Note that an exclusive lo ck is held on

the DDSDataReader (p. 1087) sam ple queue for the duration of the DDS-

QueryCondition (p. 1372) creation).

Once created, incoming samples are ﬁltered against all DDSQueryCondition

(p. 1372) ﬁlter criteria at the time of their arrival and storage into the DDS-

DataReader (p. 1087) queue.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

188 Module Documentation

The number of DDSQueryCondition (p. 1372) ﬁlters that an in-

dividual DDSDataReader (p. 1087) may create is set by DDS -

DataReaderResourceLimitsQosPolicy::max query condition ﬁlters

(p. 532), to an upper maximum of 32.

5.48.2 Filtering with ContentFilteredTopic

Set up subscriber (p. 168)

Set up a topic (p. 159)

Create a ContentFilteredTopic, of user data type Foo (p. 1443):

DDS_ContentFilteredTopic *cft = NULL;

DDS_StringSeq parameters(2);

const char* cft_param_list[] = {"1", "100"};

cft_parameters.from_array(cft_param_list, 2);

cft = participant->create_contentfilteredtopic("ContentFilteredTopic",

Foo_topic,

"value > %0 AND value < %1",

cft_parameters);

if (cft == NULL) {

printf("create_contentfilteredtopic error\n");

subscriber_shutdown(participant);

return -1;

}

Create a FooReader using the ContentFilteredTopic:

DDSDataReader *reader = NULL;

reader = subscriber->create_datareader(cft,

datareader_qos, // or DDS_DATAREADER_QOS_DEFAULT

reader_listener, // or NULL

DDS_STATUS_MASK_ALL);

if (reader == NULL) {

printf("create_datareader error\n");

subscriber_shutdown(participant);

return -1;

}

FooDataReader *Foo_reader = FooDataReader::narrow(reader);

if (Foo_reader == NULL) {

printf("DataReader narrow error\n");

subscriber_shutdown(participant);

return -1;

}

Once setup, reading samples with a DDSContentFilteredTopic

(p. 1081) is exactly the same as normal reads or takes, as decribed in

DataReader Use Cases (p. 172).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.48 Filter Use Cases 189

Changing ﬁlter crieria using set expression parameters:

cft->get_expression_parameters(cft_parameters);

DDS_String_free(cft_parameters[0]);

DDS_String_free(cft_parameters[1]);

cft_parameters[0] = DDS_String_dup("5");

cft_arameters[1] = DDS_String_dup("9");

retcode = cft->set_expression_parameters(cft_arameters);

if (retcode != DDS_RETCODE_OK) {

printf("set_expression_parameters error\n");

subscriber_shutdown(participant);

return -1;

}

5.48.3 Filtering with Query Conditions

Give n a data reader of type Foo (p. 1443)

DDSDataReader *reader = ...;

FooDataReader *Foo_reader = FooDataReader::narrow(reader);

Creating a QueryCondition

DDSQueryCondition *queryCondition = NULL;

DDS_StringSeq qc_parameters(2);

const char *qc_param_list[] = {"0","100"};

qc_parameters.from_array(qc_param_list,2);

queryCondition = reader->create_querycondition(DDS_NOT_READ_SAMPLE_STATE,

DDS_ANY_VIEW_STATE,

DDS_ALIVE_INSTANCE_STATE,

"value > %0 AND value < %1",

qc_parameters);

if (queryCondition == NULL) {

printf("create_query_condition error\n");

goto error_exit;

}

Reading matching samples with a DDSQueryCondition (p. 1372)

FooSeq data_seq;

DDS_SampleInfoSeq info_seq;

retcode = Foo_reader->read_w_condition(data_seq, info_seq,

DDS_LENGTH_UNLIMITED,

queryCondition);

if (retcode == DDS_RETCODE_NO_DATA) {

printf("no matching data\n");

} else if (retcode != DDS_RETCODE_OK) {

printf("read_w_condition error %d\n", retcode);

subscriber_shutdown(participant);

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

190 Module Documentation

return -1;

} else {

for (i = 0; i < data_seq.length(); ++i) {

if (info_seq[i].valid_data) {

/* process your data here */

}

retcode = Foo_reader->return_loan(data_seq, info_seq);

if (retcode != DDS_RETCODE_OK) {

printf("return loan error %d\n", retcode);

subscriber_shutdown(participant);

return -1;

}

DDSQueryCondition::set query parameters (p. 1373) is used sim-

ilarly to DDSContentFilteredTopic::set expression parameters

(p. 1084), and the same coding techniques can be used.

Any DDSQueryCondition (p. 1372) that have been created must be

deleted before the DDSDataReader (p. 1087) can be deleted. This can

be done using DDSDataReader::delete contained entities (p. 1093)

or manually as in:

retcode = reader->delete_readcondition(queryCondition);

5.48.4 Filtering Performance

Although RTI Connext supports ﬁltering on any ﬁeld or combination of ﬁelds

using the SQL syntax of the built-in ﬁlter, ﬁlters for keyed topics that ﬁlter solely

on the contents of key ﬁelds have the potential for much higher performance.

This is because for key ﬁeld only ﬁlters, the DDSDataReader (p. 1087) caches

the results of the ﬁlter (pass or not pass) for each instance. When another sample

of the same instance is seen at the DDSDataReader (p. 1087), the ﬁlter results

are retrieved from cache, dispensing with the need to call the ﬁlter function.

This optimization applies to all ﬁltering using the built-in SQL ﬁlter, performed

by the DDSDataReader (p.

1087), for either DDSContentFilteredTopic

(p. 1081) or DDSQueryCondition (p. 1372). This does not apply to ﬁltering

perfomed for DDSContentFilteredTopic (p. 1081) by the DDSDataWriter

(p. 1113).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.49 Creating Custom Content Filters 191

5.49 Creating Custom Content Filters

Working with custom content ﬁlters.

5.49.1 Introduction

By default, RTI Connext creates content ﬁlters with the DDS

SQL FILTER,

which implements a superset of the DDS-speciﬁed SQL WHERE clause. How-

ever, in many cases this ﬁlter may not be what you want. Some examples are:

The default ﬁlter can only ﬁlter based on the content of a sample, not on a

computation on the content of a sample. You can use a custom ﬁlter that

is customized for a speciﬁc type and can ﬁlter based on a computation of

the type members.

You want to use a diﬀerent ﬁlter language then SQL

This HOWTO explains how to write your own custom ﬁlter and is divided into

the following sections:

The Custom Content Filter API (p. 191)

Example Using C format strings (p. 192)

5.49.2 The Custom Content Filter API

A custom content ﬁlter is created by calling the DDSDomainPartici-

pant::register contentﬁlter (p. 1156) function with a DDSContentFilter

(p. 1077) that contains a compile, an evaluate function and a ﬁnalize func-

tion. DDSContentFilteredTopic (p. 1081) can b e created with DDSDo-

mainParticipant::create contentﬁlteredtopic with ﬁlter (p. 1180) to use

this ﬁlter.

A custom content ﬁlter is used by RTI Connext at the following times during

the life-time of a DDSContentFilteredTopic (p. 1081) (the function called is

shown in parenthesis).

When a DDSContentFilteredTopic (p. 1081) is created (compile

(p. 192))

When the ﬁlter parameters are changed on the DDSContentFil-

teredTopic (p. 1081) (compile (p. 192)) with DDSContentFiltered-

Topic::set expression parameters (p. 1084)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

192 Module Documentation

When a sample is ﬁltered (evaluate (p. 192)). This function is called by

the RTI Connext core with a de-serialized sample

When a DDSContentFilteredTopic (p. 1081) is deleted (ﬁnalize

(p. 192))

5.49.2.1 The compile function

The compile (p. 192) function is used to compile a ﬁlter expression and ex-

pression parameters. Please note that the term compile is intentionally loosely

deﬁned. It is up to the user to decide what this function should do and return.

See DDSContentFilter::compile (p. 1078) for details.

5.49.2.2 The evaluate function

The evaluate (p. 193) function is called each time a sample is received to de-

termine if a sample should be ﬁltered out and discarded.

See DDSContentFilter::evaluate (p. 1079) for details.

5.49.2.3 The ﬁnalize function

The ﬁnalize (p. 193) function is called when an instance of the custom content

ﬁlter is no longer needed. When this function is called, it is safe to free all

resources used by this particular instance of the custom content ﬁlter.

See DDSContentFilter::ﬁnalize (p. 1080) for details.

5.49.3 Example Using C format strings

Assume that you have a type Foo (p. 1443).

You want to write a custom ﬁlter function that will drop all samples w here the

value of Foo.x > x and x is a value determined by an expression parameter. The

ﬁlter will only be used to ﬁlter samples of type Foo (p. 1443).

5.49.3.1 Writing the Compile Function

The ﬁrst thing to note is that we can ignore the ﬁlter expression, since we

already know what the expression is. The second is that x is a parameter that

can be changed. By using this information, the compile function is very easy to

implement. Simply return the parameter string. This string will then be passed

to the evaluate function every time a sample of this type is ﬁltered.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.49 Creating Custom Content Filters 193

Below is the entire compile (p. 192) function.

DDS_ReturnCode_t MyContentFilter::compile(

void** new_compile_data, const char * /* expression */,

const DDS_StringSeq& parameters,const DDS_TypeCode* /* type_code */,

const char * /* type_clas s_na me */,

void * /* old_compile_data */) {

*new_compile_data = (void*)DDS_String_dup(parameters[0]);

return DDS_RETCODE_OK;

}

5.49.3.2 Writing the Evaluate Function

The next step is to implement the evaluate function. The evaluate function

receives the parameter string with the actual value to test against. Thus the

evaluate function must read the actual value from the parameter string before

evaluating the expression. Below is the entire evaluate (p. 192) function.

DDS_Boolean MyContentFilter::evaluate(

void* compile_data,const void* sample,const struct DDS_FilterSampleInfo * meta_data) {

char *parameter = (char*)compile_data;

DDS_Long x;

Foo *foo_sample = (Foo*)sample;

sscanf(parameter,"%d",&x);

return (foo_sample->x > x ? DDS_BOOLEAN_FALSE : DDS_BOOLEAN_TRUE);

}

5.49.3.3 Writing the Finalize Function

The last function to write is the ﬁnalize function. It is safe to free all resources

used by this particular instance of the custom content ﬁlter that is allocated in

compile. Below is the entire ﬁnalize (p. 192) function.

void MyContentFilter::finalize(

void* compile_data) {

/* free parameter string from compile function */

DDS_String_free((char *)compile_data);

}

5.49.3.4 Registering the Filter

Before the custom ﬁlter can be used, it must be registered with RTI Connext:

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

194 Module Documentation

DDSDomainParticipant *myParticipant=NULL;

/* myParticipant = .... * /

DDSContentFilter *myCustomFilter = new MyContentFilter();

if (myParticipant->register_contentfilter(

(char*)"MyCustomFilter",

myCustomFilter) != DDS_RETCODE_OK) {

printf("Failed to register custom filter\n");

}

5.49.3.5 Unregistering the Filter

When the ﬁlter is no longer needed, it can be unregistered from RTI Connext:

DDSDomainParticipant *myParticipant = NULL;

/* myParticipant = .... * /

DDSContentFilter *myCustomFilter =

myParticipant->lookup_contentfilter((char*)"MyCustomFilter");

if (myCustomFilter != NULL) {

if (myParticipant->unregister_contentfilter(

(char*)"MyCustomFilter") != DDS_RETCODE_OK) {

printf("Failed to unregister custom filter\n");

}

delete myCustomFilter;

}

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.50 Large Data Use Cases 195

5.50 Large Data Use Cases

Working with large data types.

5.50.1 Introduction

RTI Connext supports data types whose size exceeds the m aximum message

size of the underlying transports. A DDSDataWriter (p. 1113) will fragment

data samples when required. Fragments are automatically reassembled at the

receiving end.

Once all fragments of a sample have been received, the new sample is

passed to the DDSDataReader (p.

1087) which can then make it avail-

able to the user. Note that the new sample is treated as a regular sam-

ple at that point and its availability depends on standard QoS settings such

as DDS ResourceLimitsQosPolicy::max samples (p. 881) and DDS -

KEEP LAST HISTORY QOS (p. 368).

The large data feature is fully supported by all DDS API’s, so its use is mostly

transparent. Some additional considerations apply as explained below.

5.50.2 Writing Large Data

In order to use the large data feature with the DDS RELIABLE -

RELIABILITY QOS (p. 363) setting, the DDSDataWriter (p. 1113) must

be conﬁgured as an asynchronous writer (DDS ASYNCHRONOUS -

PUBLISH MODE QOS (p. 422)) with associated DDSFlowController

(p. 1259).

While the use of an asynchronous writer and ﬂow controller is optional when us-

ing the DDS BEST EFFORT RELIABILITY QOS (p. 363) setting, most

large data use cases will beneﬁt from the use of a ﬂow controller to prevent

ﬂooding the network when fragments are being sent.

Set up writer (p. 166)

Add ﬂow control (p. 161)

5.50.3 Receiving Large Data

Large data is supported by default and in most cases, no further changes are

required.

The DDS DataReaderResourceLimitsQosPolicy (p. 521) allows tuning

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

196 Module Documentation

the resources available to the DDSDataReader (p. 1087) for reassembling frag-

mented large data.

Set up reader (p. 172)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.51 Documentation Roadmap 197

5.51 Documentation Roadmap

This section contains a roadmap for the new user with pointers on what to read

ﬁrst.

If you are new to RTI Connext, we recommend starting in the following order:

See the Getting Started Guide. This document provides download and

installation instructions. It also lays out the core value and concepts

behind the product and takes you step-by-step through the creation of a

simple example application.

The User’s Manual describes the features of the product and how to use

them. It is organized around the structure of the DDS APIs and certain

common high-level tasks.

The documentation in the DDS API Reference (p. 203) provides an

overview of API classes and modules for the DDS data-centric publish-

subscribe (DCPS) package from a programmer’s perspective. Start by

reading the documentation on the main page.

After reading the high level module documentation, look at the Publi-

cation Example (p. 154) and Subscription Example (p. 155) for step-

by-step examples of creating a publication and subscription. These are

hyperlinked code snippets to the full API documentation, and provide a

good place to begin learning the APIs.

Next, work through your own application using the example code ﬁles

generated by rtiddsgen (p. 220).

To integrate similar code into your own application and build system, you

will likely need to refer to the Platform Notes.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

198 Module Documentation

5.52 Conve ntions

This section describes the conventions used in the API documentation.

5.52.1 Unsupported Features

[Not supported (optional)] This note means that the optional feature from

the DDS speciﬁcation is not supported in the current release.

5.52.2 API Naming Conventions

5.52.2.1 Structure & Class Names

RTI Data Distribution Service 4 makes a distinction between value types and

interface types. Value types are types such as primitives, enumerations, strings,

and structures whose identity and equality are determined solely by explicit

state. Interface types are those abstract opaque data types that conceptually

have an identity apart from their explicit state. Examples include all of the

DDSEntity (p. 1253) subtypes, the DDSCondition (p. 1075) subtypes, and

DDSWaitSet (p. 1433). Instances of value types are frequently transitory and

are declared on the stack. Instances of interface types typically have longer

lifecycles, are acc ess ible by pointer only, and may be managed by a factory

object.

Value and interface types are distinguished by their names: value types have

names beginning with ”DDS ” (i.e. with an underscore); interface types have

names beginning with ”DDS” (i.e. with no underscore). Another way to think

of it: C-style types – structures, enumerations, etc. – have names beginning

with ”DDS ”; C++ classes have names beginning with ”DDS.”

5.52.3 API Documentation Terms

In the API documentation, the term module refers to a logical grouping of

documentation and elements in the API.

At this time, typedefs that occur in the API, such as DDS ReturnCode -

t (p. 315) do not show up in the compound list or indices. This is a known

limitation in the generated HTML.

5.52.4 Stereotypes

Commonly used stereotypes in the API documentation include the following.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.52 Conventions 199

5.52.4.1 Extensions

<<eXtension>> ( p. 199)

– An RTI Connext product extension to the DDS standard speciﬁca-

tion.

– The extension APIs complement the standard APIs speciﬁed by the

OMG DDS spe ciﬁcation. They are provided to improve product

usability and enable access to product-speciﬁc features such as plug-

gable transports.

5.52.4.2 Experimental

<<experimental>> ( p. 199)

– RTI Connext experimental features are used to evaluate new features

and ge t user feedback.

– These features are not guaranteed to be fully supported and might be

implemented only of some of the programming languages supported

bt RTI Connext

– The functional APIs corresponding to experimental features can be

distinguished from other APIs by the suﬃx ’ exp’.

– Experimental features may or may not appear in future product re-

leases.

– The name of the experimental features APIs will change if they be-

come oﬃcially supported. At the very least the suﬃx ’ exp’ will be

removed.

– Experimental features should not be used in production.

5.52.4.3 Types

<<interface>> ( p. 199)

– Pure interface type with no state.

– Languages such as Java natively support the concept of an inter-

face type, which is a collection of method signatures devoid of any

dynamic state.

– In C++, this is achieved via a class with all pure virtual metho ds

and devoid of any instance variables (ie no dynamic state).

– Interfaces are generally organized into a type hierarchy. Static type-

casting along the interface type hierarchy is ”safe” for valid objects.

<<generic>> ( p. 199)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

200 Module Documentation

– A generic type is a skeleton class written in terms of generic pa-

rameters. Type-speciﬁc instantiations of such types are convention-

ally referred to in this documentation in terms of the hypothetical

type ”Foo”; for example: FooSeq (p. 1494), FooDataType, Foo-

DataWriter (p. 1475), and FooDataReader (p. 1444).

– For portability and eﬃciency, we implement generics using C prepro-

cessor macros, rather than using C++ templates.

– A generic type interface is declared via a #deﬁne macro.

– Concrete types are generated from the generic type statically at com-

pile time. The implementation of the concrete types is provided via

the generic macros which can then be compiled as normal C or C++

code.

<<singleton>> ( p. 200)

– Singleton class . There is a single instance of the class.

– Generally ac cc ess ed via a get instance() static method.

5.52.4.4 Method Parameters

<<in>> ( p. 200)

– An input parameter.

<<out>> ( p. 200)

– An output parameter.

<<inout>> ( p. 200)

– An input and output parameter.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.53 Using DDS:: Namespace 201

5.53 Using DDS:: Namespace

This section describes the C++ namespace support in the DDS API.

5.53.1 DDS Namespace Support

In this doc umentation, all C++ classes , value types, interface types and con-

stants have names beginning with either ”DDS ” or ”DDS”. Alternatively,

DDS namespace can also be used to refer to all these classes, types or constant.

All the C++ API that begins with either ”DDS ” or ”DDS” can be re-

placed with its namespace equivalent. For example, DDSDomainPartici-

pant (p. 1139) has a namespace equivalent of DDS::DomainParticipant,

and DDS DomainParticipantQos (p. 588) has a namespace equivalent of

DDS::DomainParticipantQos.

In order to use the DDS namespace, an additional header ﬁle, ndds -

namespace cpp.h , will need to be included in your source ﬁle:

#include "ndds/ndds_cpp.h"

#include "ndds/ndds_namespace_cpp.h"

DDS::DomainParticipant *participant = NULL;

DDS::DomainParticipantQos participant_qos;

DDS::DomainParticipantListener *listener = NULL;

DDS::StatusKind status_kind = DDS::INCONSISTENT_TOPIC_STATUS;

DDS::Long counter = 0L;

If the namespace header ﬁle is not included in the source ﬁle, DDS namespace

cannot be used in the RTI Connext API.

5.53.2 DDS Namespace and Primitive Types

By default, DDS namespace supp ort for primitive types are included. With

DDS namespace support, the diﬀerence between DDS types and native types

can just be the capitalization in some cases:

#include "ndds/ndds_cpp.h"

#include "ndds/ndds_namespace_cpp.h"

using namespace DDS;

Long ddsCounter = 0L;

long nativeCounter = 0L;

If you want to exclude the DDS namespace support for primitive

types, you can deﬁne NDDS EXCLUDE PRIMITIVE TYPES FROM -

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

202 Module Documentation

NAMESPACE in you application before including the namespace header ﬁle.

DDS namespace support for primitive types will then be excluded:

#include "ndds/ndds_cpp.h"

#define NDDS_EXCLUDE_PRIMITIVE_TYPES_FROM_NAMESPACE

#include "ndds/ndds_namespace_cpp.h"

using namespace DDS;

DDS_Long ddsCounter = 0;

long nativeCounter = 0;

For the rest of the documentation, the DDS preﬁx is used for all class

/types/constants names. However, all the API with the DDS preﬁx can be

replaced with DDS namespace instead if the namespace header ﬁle is included.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.54 DDS API Reference 203

5.54 DDS API Reference

RTI Connext modules following the DDS module deﬁnitions.

Modules

Domain Module

Contains the DDSDomainParticipant ( p. 1139) class that acts as an en-

trypoint of RTI Connext and acts as a factory for many of the classes. The

DDSDomainParticipant ( p. 1139) also acts as a container for the other

objects that make up RTI Connext.

Topic Module

Contains the DDSTopic ( p. 1419), DDSContentFilteredTopic ( p. 1081),

and DDSMultiTopic ( p. 1322) classes, the DDSTopicListener ( p. 1430)

interface, and more generally, all that is needed by an application to deﬁne

DDSTopic ( p. 1419) objects and attach QoS policies to them.

Publication Module

Contains the DDSFlowController ( p. 1259), DDSPublisher ( p. 1346),

and DDSDataWriter ( p. 1113) classes as well as the DDSPublisherLis-

tener ( p. 1370) and DDSDataWriterListener ( p. 1133) interfaces, and

more generally, all that is needed on the publication side.

Subscription Module

Contains the DDSSubscriber ( p. 1390), DDSDataReader ( p. 1087),

DDSReadCondition ( p. 1374), and DDSQueryCondition ( p. 1372)

classes, as well as the DDSSubscriberListener ( p. 1414) and DDS-

DataReaderListener ( p. 1108) interfaces, and more generally , all that is

needed on the subscription side.

Infrastructure Module

Deﬁnes the abstract classes and the interfaces that are reﬁned by the other

modules. Contains common deﬁnitions such as return codes, status values,

and QoS policies.

Queries and Filters Syntax

5.54.1 Detailed Description

RTI Connext modules following the DDS module deﬁnitions.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

204 Module Documentation

5.54.2 Overview

Information ﬂow s with the aid of the following constructs: DDSPublisher

(p. 1346) and DDSDataWriter (p. 1113) on the sending side, DDSSub-

scriber (p. 1390) and DDSDataReader (p. 1087) on the receiving side.

A DDSPublisher (p. 1346) is an object responsible for data distribution.

It may publish data of diﬀerent data types. A TDataWriter acts as a typed

(i.e. each DDSDataWriter (p. 1113) object is dedicated to one applica-

tion data type) accessor to a publisher. A DDSDataWriter (p. 1113)

is the object the application must use to communicate to a publisher the

existence and value of data objects of a given type. When data object

values have been communicated to the publisher through the appropriate

data-writer, it is the publisher’s responsibility to perform the distribution

(the publisher will do this according to its own QoS, or the QoS attached

to the corresponding data-writer). A publication is deﬁned by the associ-

ation of a data-writer to a publisher. This ass ociation expresses the intent

of the application to publish the data described by the data-writer in the

context provided by the publisher.

A DDSSubscriber (p. 1390) is an object responsible for receiving pub-

lished data and making it available (ac cording to the Subscriber’s QoS)

to the receiving application. It m ay receive and dispatch data of diﬀerent

speciﬁed types. To access the received data, the application must use a

typed TDataReader attached to the subscriber. Thus, a subscription is

deﬁned by the as sociation of a data-reader with a subscriber. This as-

sociation expresses the intent of the application to subscribe to the data

described by the data-reader in the context provided by the subscriber.

DDSTopic (p. 1419) objects conceptually ﬁt between publications and sub-

scriptions. Publications must be known in such a way that subscriptions can re-

fer to them unambiguously. A DDSTopic (p. 1419) is meant to fulﬁll that pur-

pose: it associates a name (unique in the domain i.e. the set of applications that

are communicating with each other), a data type, and QoS related to the data

itself. In addition to the topic QoS, the QoS of the DDSDataWriter (p. 1113)

associated with that Topic and the QoS of the DDSPublisher (p. 1346) as-

sociated to the DDSDataWriter (p. 1113) control the behavior on the pub-

lisher’s side, while the corresponding DDSTopic (p. 1419), DDSDataReader

(p. 1087) and DDSSubscriber (p. 1390) QoS control the behavior on the sub-

scriber’s side.

When an application wishes to publish data of a given type, it must create

a DDSPublisher (p. 1346) (or reuse an already created one) and a DDS-

DataWriter (p. 1113) with all the characteristics of the desired publication.

Similarly, when an application wishes to receive data, it must create a DDSSub-

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.54 DDS API Reference 205

scriber (p. 1390) (or reuse an already created one) and a DDSDataReader

(p. 1087) to deﬁne the subscription.

5.54.3 Conceptual Model

The overall conceptual model is shown below.

Notice that all the main communication objects (the specializations of Entity)

follow uniﬁed patterns of:

Supp orting QoS (made up of several QosPolicy); QoS provides a generic

mechanism for the application to control the behavior of the Service and

tailor it to its needs. Each DDSEntity (p. 1253) supports its own spe-

cialized kind of QoS policies (see QoS Policies (p. 331)).

Accepting a DDSListener (p. 1318); listeners provide a generic mecha-

nism for the middleware to notify the application of relevant asynchronous

events, such as arrival of data corresponding to a subscription, violation of

a QoS setting, etc. Each DDSEntity (p. 1253) supports its own special-

ized kind of listener. Listeners are related to changes in status conditions

(see Status Kinds (p. 317)).

Note that only one Listener per entity is allowed (instead of a list of

them). The reason for that choice is that this allows a much simpler (and,

thus, more eﬃcient) implementation as far as the middleware is concerned.

Moreover, if it were required, the application could easily implement a

listener that, when triggered, triggers in return attached ’sub-listeners’.

Accepting a DDSStatusCondition (p. 1376) (and a set of DDSRead-

Condition (p. 1374) objects for the DDSDataReader (p. 1087)); condi-

tions (in conjunction with DDSWaitSet (p. 1433) objects) provide sup-

port for an alternate communication style between the middleware and

the application (i.e., wait-based rather than notiﬁcation-based).

All DCPS entities are attached to a DDSDomainParticipant (p. 1139). A

domain participant represents the local membership of the application in a do-

main. A domain is a distributed concept that links all the applications able to

communicate with each other. It represents a communication plane: only the

publishers and the subscribers attached to the same domain may interact.

DDSDomainEntity (p. 1138) is an intermediate object whose only purpose is

to state that a DomainParticipant cannot contain other domain participants.

At the DCPS level, data types represent information that is sent atomically.

For performance reasons, only plain data structures are handled by this level.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

206 Module Documentation

By default, each data modiﬁcation is propagated individually, indep e ndently,

and uncorrelated with other modiﬁcations. However, an application may re-

quest that seve ral modiﬁcations be sent as a whole and interpreted as such at

the recipient side. This functionality is oﬀered on a Publisher/Subscriber ba-

sis. That is, these relationships can only b e speciﬁed among DDSDataWriter

(p. 1113) objects attached to the same DDSPublisher (p. 1346) and retrieved

among DDSDataReader (p. 1087) objects attached to the same DDSSub-

scriber (p. 1390).

By deﬁnition, a DDSTopic (p. 1419) corresponds to a single data type. How-

ever, several topics may refer to the same data type. Therefore, a DDSTopic

(p. 1419) identiﬁes data of a s ingle type, ranging from one single instance to a

whole collection of instances of that given type. This is shown below for the

hypothetical data type Foo (p. 1443).

In case a set of instances is gathered under the same topic, diﬀerent instances

must be distinguishable. This is achieved by means of the values of some data

ﬁelds that form the key to that data set. The key description (i.e., the list of

data ﬁelds whose value forms the key) has to be indicated to the middleware.

The rule is s imple: diﬀerent data samples with the same key value represent

successive values for the same instance, while diﬀerent data samples with diﬀer-

ent key values represent diﬀerent instances. If no key is provided, the data set

associated with the DDSTopic (p. 1419) is restricted to a single instance.

Topics need to be known by the middleware and potentially propagated. Topic

objects are created using the create operations provided by DDSDomainPar-

ticipant (p. 1139).

The interaction style is straightforward on the publisher’s side: when the appli-

cation decides that it wants to make data available for publication, it calls the

appropriate operation on the related DDSDataWriter (p. 1113) (this, in turn,

will trigger its DDSPublisher (p. 1346)).

On the subscriber’s side however, there are more choices: relevant information

may arrive when the application is busy doing something else or when the appli-

cation is just waiting for that information. Therefore, depending on the way the

application is designed, asynchronous notiﬁcations or synchronous access may

be more appropriate. Both interaction modes are allowed, a DDSListener

(p. 1318) is used to provide a callback for synchronous ac ce ss and a DDSWait-

Set (p. 1433) associated with one or several DDSCondition (p. 1075) objects

provides asynchronous data access.

The same synchronous and asynchronous interaction modes can also be used

to access changes that aﬀect the middleware communication status (see Sta-

tus Kinds (p. 317)). For instance, this may occur when the middleware asyn-

chronously detects an inconsistency. In addition, other middleware information

that may be relevant to the application (such as the list of the existing topics)

is made available by means of built-in topics (p. 42) that the application can

access as plain application data, using built-in data-readers.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.54 DDS API Reference 207

5.54.4 Modules

DCPS c onsists of ﬁve modules:

Infrastructure module (p. 118) deﬁnes the abstract classes and the

interfaces that are reﬁned by the other modules. It also provides support

for the two interaction styles (notiﬁcation-based and wait-based) with the

middleware.

Domain module (p. 32) contains the DDSDomainParticipant

(p. 1139) class that acts as an entrypoint of the Service and acts as a

factory for many of the classes. The DDSDomainParticipant (p. 1139)

also acts as a container for the other objects that make up the Service.

Topic module (p. 49) contains the DDSTopic (p. 1419) class, the

DDSTopicListener (p. 1430) interface, and more generally, all that is

needed by the application to deﬁne DDSTopic (p. 1419) objects and at-

tach QoS policies to them.

Publication module (p. 82) contains the DDSPublisher (p. 1346) and

DDSDataWriter (p. 1113) classes as well as the DDSPublisherLis-

tener (p. 1370) and DDSDataWriterListener (p. 1133) interfaces, and

more generally, all that is needed on the publication side.

Subscription module (p. 95) contains the DDSSubscriber (p. 1390),

DDSDataReader (p. 1087), DDSReadCondition (p. 1374), and

DDSQueryCondition (p. 1372) classes, as well as the DDSSub-

scriberListener (p. 1414) and DDSDataReaderListener (p. 1108) in-

terfaces, and more generally, all that is needed on the subscription side.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

208 Module Documentation

5.55 Queries and Filters Syntax

5.55.1 Syntax for DDS Queries and Filters

A subset of SQL syntax is used in several parts of the speciﬁcation:

The filter expression in the DDSContentFi lteredTopic (p. 1081)

The query expression in the DDSQueryCondition (p. 1372)

The topic expression in the DDSMultiTopic (p. 1322)

Those expressions may use a subset of SQL, extended with the possibility to

use program variables in the SQL expression. The allowed SQL expressions are

deﬁned w ith the BNF-grammar below.

The following notational conventions are made:

NonTerminals are typeset in italics.

’Terminals’ are quoted and typeset in a ﬁxed width font. They are

written in upper case in most cases in the BNF-grammar below, but should

be case insensitive.

TOKENS are typeset in bold.

The notation (element // ’,’) represents a non-empty comma-separated

list of elements.

5.55.2 SQL grammar in BNF

Expression ::= FilterExpression

| TopicExpression

| QueryExpression

FilterExpression ::= Condition

TopicExpression ::= SelectFrom { Where } ’;’

QueryExpression ::= { Condition }{ ’ORDER BY’ ( FIELD-

NAME // ’,’) }

SelectFrom ::= ’SELECT’ Aggregation ’FROM’ Selection

Aggregation ::= ’*’

| ( SubjectFieldSpec // ’,’)

SubjectFieldSpec ::= FIELDNAME

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.55 Queries and Filters Syntax 209

| FIELDNAME ’AS’ IDENTIFIER

| FIELDNAME IDENTIFIER

Selection ::= TOPICNAME

| TOPICNAME NaturalJoin JoinItem

JoinItem ::= TOPICNAME

| TOPICNAME NaturalJoin JoinItem

| ’(’ TOPICNAME NaturalJoin JoinItem ’)’

NaturalJoin ::= ’INNER JOIN’

| ’INNER NATURAL JOIN’

| ’NATURAL JOIN’

| ’NATURAL INNER JOIN’

Where ::= ’WHERE’ Condition

Condition ::= Predicate

| Condition ’AND’ Condition

| Condition ’OR’ Condition

| ’NOT’ Condition

| ’(’ Condition ’)’

Predicate ::= ComparisonPredicate

| BetweenPredicate

ComparisonPredicate ::= ComparisonTerm RelOp ComparisonTerm

ComparisonTerm ::= FieldIdentiﬁer

| Parameter

BetweenPredicate ::= FieldIdentifier ’BETWEEN’ Range

| FieldIdentifier ’NOT BETWEEN’ Range

FieldIdentifier ::= FIELDNAME

| IDENTIFIER

RelOp ::= ’=’ | ’>’ | ’>=’ | ’<’ | ’<=’ | ’<>’ | ’LIKE’ | ’MATCH’

Range ::= Parameter ’AND’ Parameter

Parameter ::= INTEGERVALUE

| CHARVALUE

| FLOATVALUE

| STRING

| ENUMERATEDVALUE

| BOOLEANVALUE

| PARAMETER

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

210 Module Documentation

Note – INNER JOIN, INNER NATURAL JOIN, NATURAL JOIN, and NAT-

URAL INNER JOIN are all aliases, in the sense that they have the same se-

mantics. They are all supported because they all are part of the SQL standard.

5.55.3 Token expression

The syntax and meaning of the tokens used in the SQL grammar is described

as follows:

IDENTIFIER - An identiﬁer for a FIELDNAME, and is deﬁned as any

series of characters ’a’, ..., ’z’, ’A’, ..., ’Z’, ’0’, ..., ’9’, ’ ’ but may not start

with a digit.

Formal notation:

IDENTIFIER: LETTER ( PART LETTER )*

where LETTER : [ "A"-"Z"," ","a"-"z" ]

PART LETTER : [ "A"-"Z"," ","a"-"z","0"-"9" ]

FIELDNAME - A ﬁeldname is a reference to a ﬁeld in the data structure.

The dot ’.’ is used to navigate through nested structures. The number of

dots that may be used in a FIELDNAME is unlimited. The FIELDNAME

can refer to ﬁelds at any depth in the data structure. The names of the ﬁeld

are those speciﬁed in the IDL deﬁnition of the corresponding structure,

which may or may not match the ﬁeldnames that appear on the language-

speciﬁc (e.g., C/C++, Java) mapping of the structure. To reference to the

n+1 element in an array or sequence, use the notation ’[n]’, where n is a

natural number (zero included). FIELDNAME must resolve to a primitive

IDL type; that is either boolean, octet, (unsigned) short, (unsigned) long,

(unsigned) long long, ﬂoat double, char, wchar, string, wstring, or enum.

Formal notation:

FIELDNAME: FieldNamePart ( "." FieldNamePart )*

where FieldNamePart : IDENTIFIER ( "[" Index "]" )*

Index> : (["0"-"9"])+

| ["0x","0X"](["0"-"9", "A"-"F", "a"-"f"])+

Primitive IDL types referenced by FIELDNAME are treated as diﬀerent types

in Predicate according to the following table:

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.55 Queries and Filters Syntax 211

Predicate Data Type IDL Type

BOOLEANVALUE boolean

INTEGERVALUE octet, (unsigned) short, (unsigned)

long, (unsigned) long long

FLOATVALUE ﬂoat, double

CHARVALUE char, wchar

STRING string, w string

ENUMERATEDVALUE enum

TOPICNAME - A topic name is an identiﬁer for a topic, and is deﬁned

as any series of characters ’a’, ..., ’z’, ’A’, ..., ’Z’, ’0’, ..., ’9’, ’ ’ but may

not start with a digit.

Formal notation:

TOPICNAME : IDENTIFIER

INTEGERVALUE - Any series of digits, optionally preceded by a plus

or minus sign, representing a decimal integer value within the range of the

system. A hexadecimal number is preceded by 0x and must be a valid

hexadecimal expression.

Formal notation:

INTEGERVALUE : (["+","-"])? (["0"-"9"])+ [("L","l")]?

| (["+","-"])? ["0x","0X"](["0"-"9", "A"-"F", "a"-"f"])+ [("L","l")]?

CHARVALUE - A single character enclosed between single quotes.

Formal notation:

CHARVALUE : "’" (~["’"])? "’"

FLOATVALUE - Any series of digits, optionally preceded by a plus or

minus sign and optionally including a ﬂoating point (’.’). A power-of-ten

expression may be postﬁxed, which has the syntax en or En, where n is

a number, optionally preceded by a plus or minus sign.

Formal notation:

FLOATVALUE : (["+","-"])? (["0"-"9"])* (".")? (["0"-"9"])+ ( EXPONENT )?

where EXPONENT : ["e","E"] (["+","-"])? (["0"-"9"])+

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

212 Module Documentation

STRING - Any series of characters encapsulated in single quotes, except

the single quote itself.

Formal notation:

STRING : "’" (~["’"])* "’"

ENUMERATEDVALUE - An enumerated value is a reference to a

value declared within an enumeration. Enumerated values consist of the

name of the enumeration lab el enclosed in single quotes. The name used

for the enumeration label must correspond to the label names speciﬁed in

the IDL deﬁnition of the enumeration.

Formal notation:

ENUMERATEDVALUE : "’" ["A" - "Z", "a" - "z"] ["A" - "Z", "a" - "z", " ", "0" - "9"]* "’"

BOOLEANVALUE - Can either be ’TRUE’ or ’FALSE’, case insensi-

tive.

Formal notation (case insensitive):

BOOLEANVALUE : ["TRUE","FALSE"]

PARAMETER - A parameter is of the form %n, where n represents a

natural number (zero included) smaller than 100. It refers to the n + 1

argument in the give n context. Argument can only in primitive type

value format. It cannot be a FIELDNAME.

Formal notation:

PARAMETER : "%" (["0"-"9"])+

5.55.4 String Parameters

Strings used as parameter values must contain the enclosing quotation marks

(’) within the parameter value, and not place the quotation marks within the

expression statement. For example, the following expression is legal:

" symbol MATCH %0 " with parameter 0 = " ’IBM’ "

whereas the following expression will not compile:

" symbol MATCH ’%0’ " with parameter 0 = " IBM "

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.55 Queries and Filters Syntax 213

5.55.5 Type compatability in Predicate

Only certain combination of type comparisons are valid in Predicate. The fol-

lowing table marked all the compatible pairs with ’YES’:

BOOLEAN-

VALUE

INTE-

GERVALUEFLOAT-

VALUE

CHAR-

VALUE

STRING

ENU-

MER-

ATED-

VALUE

BOOLEAN

YES

INTE-

GERVALUE

YES YES

FLOAT-

VALUE

YES YES

CHAR-

VALUE

YES YES YES

STRING

YES

YES(∗1)

YES

ENU-

MER-

ATED-

VALUE

YES

YES(∗2) YES(∗2) YES(∗3)

(∗1) See SQL Extension: Regular Expression Matching (p. 213)

(∗2) Because the formal notation of the Enumeration values, they are

compatible with string and char literals, but they are not compatible with

string or char variables, i.e., ”MyEnum=’EnumValue’” would be correct,

but ”MyEnum=MyString” is not allowed.

(∗3) Only for same type Enums.

5.55.6 SQL Extension: Regular Expression Matching

The relational operator MATCH may only be used with string ﬁelds. The right-

hand operator is a string pattern. A string pattern speciﬁes a template that

the left-hand ﬁeld value must match. The characters ,/?∗[]-

∧

!% have special

meanings.

MATCH is case-sensitive.

The pattern allows limited ”wild card” matching under the following rules:

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

214 Module Documentation

Character Meaning

, ”,” separates a list of alternate

patterns. The ﬁeld string is

matched if it matches one or more

of the patterns.

/ ”/” in the pattern string matches a

/ in the ﬁeld string. This character

is used to separate a sequence of

mandatory substrings.

? ”?” in the pattern string matches

any single non-special characters in

the ﬁeld string.

∗ ”∗” in the pattern string matches 0

or more non-special characters in

ﬁeld string.

[charlist] Matches any one of the characters

from the list of characters in

charlist.

[s-e] Matches any character any

character from s to e, inclusive.

% ”%” is used to designate ﬁlter

expressions parameters.

[!charlist] or [

∧

charlist] Matches any characters not in

charlist (not supported).

[!s-e] or [

∧

s-e] Matches any characters not in the

interval [s-e] (not supported).

\ Escape character for special

characters (not supported)

The syntax is similar to the POSIX fnmatch syntax (1003.2-1992 section B.6).

The MATCH syntax is also similar to the ’subject’ strings of TIBCO Ren-

dezvous.

5.55.7 Examples

Assuming Topic ”Location” has as an associated type a structure with ﬁelds

”ﬂight id, x, y, z ”, and Topic ”FlightPlan” has as ﬁelds ”ﬂight id, source, des-

tination”. The following are examples of using these expressions.

Example of a ﬁlter expression (for DDSContentFilteredTopic (p. 1081))

or a query expression (for DDSQueryCondition (p. 1372)):

"z < 1000 AND x < 23"

Examples of a ﬁlter expression using MATCH (for DDSContentFiltered-

Topic (p. 1081)) operator:

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.55 Queries and Filters Syntax 215

"symbol MATCH ’NASDAQ/GOOG’"

"symbol MATCH ’NASDAQ/[A-M]∗’"

Example of a topic expression (for DDSMultiTopic (p. 1322) [Not sup-

ported (optional)]):

"SELECT flight id, x, y, z AS height FROM ’Location’ NATURAL JOIN

’FlightPlan’ WHERE height < 1000 AND x <23"

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

216 Module Documentation

5.56 RT I Connext API Reference

RTI Connext product speciﬁc API’s.

Modules

Clock Selection

APIs related to clock selection.

Multi-channel DataWriters

APIs related to Multi-channel DataWriters.

Pluggable Transports

APIs related to RTI Connext pluggable transports.

Conﬁguration Utilities

Utility API’s independent of the DDS standard.

Unsupported Utilities

Unsupported APIs used by examples in the RTI Connext distribution as well

as in rtiddsgen-generated examples.

Durability and Persistence

APIs related to RTI Connext Durability and Persistence.

System Properties

System Properties.

Conﬁguring QoS Proﬁles with XML

APIs related to XML QoS Proﬁles.

5.56.1 Detailed Description

RTI Connext product speciﬁc API’s.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.57 Programming How-To’s 217

5.57 Programming How-To’s

These ”How To”s illustrate how to apply RTI Connext APIs to common use

cases.

Modules

Publication Example

A data publication example.

Subscription Example

A data subscription example.

Participant Use Cases

Working with domain partcipants.

Topic Use Cases

Working with topics.

FlowController Use Cases

Working with ﬂow controllers.

Publisher Use Cases

Working with publishers.

DataWriter Use Cases

Working with data writers.

Subscriber Use Cases

Working with subscribers.

DataReader Use Cases

Working with data readers.

Entity Use Cases

Working with entities.

Waitset Use Cases

Using wait-sets and conditions.

Transport Use Cases

Working with pluggable transports.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

218 Module Documentation

Filter Use Cases

Working with data ﬁlters.

Creating Custom Content Filters

Working with custom content ﬁl ters.

Large Data Use Cases

Working with large data types.

5.57.1 Detailed Description

These ”How To”s illustrate how to apply RTI Connext APIs to common use

cases.

These are a good starting point to familiarize yourself with DDS. You can use

these code fragments as ”templates” for writing your own code.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.58 Programming Tools 219

5.58 Programming Tools

Modules

rtiddsgen

Generates source code from data types declared in IDL, XML, XSD, or

WSDL ﬁles.

rtiddsping

Sends or receives simple messages using RTI Connext.

rtiddsspy

Debugging tool which receives all RTI Connext communication.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

220 Module Documentation

5.59 rtiddsgen

Generates source code from data types declared in IDL, XML, XSD, or WSDL

ﬁles. Generates code necessary to allocate, send, receive, and print user-deﬁned

data types.

5.59.1 Usage

rtiddsgen [-d <outdir>]

[-language <C|C++|Java|C++/CLI|C#|Ada>]

[-namespace]

[-package <packagePrefix>]

[-example <arch>]

[-replace]

[-debug]

[-corba [client header file] [-orb <CORBA ORB>]]

[-optimization <level of optimization>]

[-stringSize <Unbounded strings size>]

[-sequenceSize <Unbounded sequences size>]

[-notypecode]

[-ppDisable]

[-ppPath <preprocessor executable>]

[-ppOption <option>]

[-D <name>[=<value>]]

[-U <name>]

[-I <directory>]

[-noCopyable]

[-use42eAlignment]

[-enableEscapeChar]

[-typeSequenceSuffix <Suffix>]

[-dataReaderSuffix <Suffix>]

[-dataWriterSuffix <Suffix>]

[-convertToXml |

-convertToXsd |

-convertToWsdl |

-convertToIdl]

[-convertToCcl]

[-convertToCcs]

[-expandOctetSeq]

[-expandCharSeq]

[-metp]

[-version]

[-help]

[-verbosity [1-3]]

[[-inputIdl] <IDLInputFile.idl> |

[-inputXml] <XMLInputFile.xml> |

[-inputXsd] <XSDInputFile.xsd> |

[-inputWsdl] <WSDLInputFile.wsdl>]

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.59 rtiddsgen 221

-d Speciﬁes where to put the generated ﬁles. If omitted, the input ﬁle’s directory

is used.

-language Generates output for only the language speciﬁed. The default is

C++.

Use of generated Ada 2005 code requires installation of RTI Ada 2005 Language

Supp ort. Please contact [email protected] for more information.

-namespace Speciﬁes the use of C++ namespaces (for C++ only).

-package Speciﬁes a packagePreﬁx to use as the root package (for Java only).

-example Generates example programs and makeﬁles (for UNIX-based sys-

tems) or workspace and project ﬁles (for Windows systems) based on the input

types description ﬁle.

The <arch> parameter speciﬁes the architecture for the example makeﬁles.

For -language C/C++, valid options for <arch> are:

sparcSol2.9gcc3.2, sparcSol2.9cc5.4, sparcSol2.10gcc3.4.2,

sparc64Sol2.10gcc3.4.2, i86Sol2.9gcc3.3.2, i86Sol2.10gcc3.4.4,

x64Sol2.10gcc3.4.3,

x64Darwin10gcc4.2.1,

i86Linux2.6gcc3.4.3, x64Linux2.6gcc3.4.5, i86Linux2.6gcc4.1.1,

x64Linux2.6gcc4.1.1, i86Linux2.6gcc4.1.2, x64Linux2.6gcc4.1.2,

i86Linux2.6gcc4.2.1, i86Linux2.6gcc4.4.3, x64Linux2.6gcc4.4.3,

x64Linux2.6gcc4.3.4, i86Linux2.6gcc4.4.5, x64Linux2.6gcc4.4.5,

i86Linux2.6gcc3.4.6, i86RedHawk5.1gcc4.1.2, i86RedHawk5.4gcc4.2.1,

x64Linux2.6gcc4.4.4, x64Linux2.6gcc4.5.1, i86Suse10.1gcc4.1.0,

x64Suse10.1gcc4.1.0, cell64Linux2.6gcc4.5.1, armv7leLinux2.6gcc4.4.1,

i86WRLinux2.6gcc4.3.2, x64WRLinux2.6gcc4.4.1,

ppc4xxFPLinux2.6gcc4.3.3, ppc7400Linux2.6gcc3.3.3,

ppc85xxLinux2.6gcc4.3.2, ppc85xxWRLinux2.6gcc4.3.2,

i86Win32VS2005, x64Win64VS2005, i86Win32VS2008, x64Win64VS2008,

i86Win32VS2010, x64Win64VS2010,

ppc85xxInty5.0.11.xes-p2020, mpc8349Inty5.0.11.mds8349, pentiu-

mInty10.0.0.pcx86,

ppc7400Lynx4.0.0gcc3.2.2, ppc7400Lynx4.2.0gcc3.2.2,

ppc750Lynx4.0.0gcc3.2.2, ppc7400Lynx5.0.0gcc3.4.3, i86Lynx4.0.0gcc3.2.2,

ppc604Vx5.5gcc, ppc603Vx5.5gcc, ppc 604Vx6.3gcc3.4.4, ppc604Vx6.3gcc3.4.4 -

rtp, ppc604Vx6.5gcc3.4.4, ppc604Vx6.5gcc3.4.4 rtp, pentiumVx6.6gcc4.1.2,

pentiumVx6.6gcc4.1.2 rtp, ppc405Vx6.6gcc4.1.2, ppc405Vx6.6gcc4.1.2 -

rtp, ppc604Vx6.6gcc4.1.2, ppc604Vx6.6gcc4.1.2 rtp, pen-

tiumVx6.7gcc4.1.2, pentiumVx6.7gcc4.1.2 rtp, ppc604Vx6.7gcc4.1.2,

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

222 Module Documentation

ppc604Vx6.7gcc4.1.2 smp, ppc604Vx6.7gcc4.1.2 rtp, ppc604Vx6.8gcc4.1.2,

ppc604Vx6.8gcc4.1.2 rtp, pentiumVx6.8gcc4.1.2, pentiumVx6.8gcc4.1.2 -

rtp, ppc604Vx6.9gcc4.3.3, ppc604Vx6.9gcc4.3.3 rtp, pen-

tiumVx6.9gcc4.3.3, pentiumVx6.9gcc4.3.3 rtp, pentium64Vx6.9gcc4.3.3, pen-

tium64Vx6.9gcc4.3.3 rtp, ppc604VxT2.2.2gcc3.3.2, ppc604VxT2.2.2gcc3.3.2 -

v6, ppc85xxVxT2.2.3gcc3.3.2, sbc8641Vx653-2.3gcc3.3.2, simpcVx653-

2.3gcc3.3.2,

p5AIX5.3xlc9.0, 64p5AIX5.3xlc9.0,

i86QNX6.4.1qcc gpp i86QNX6.5qcc gpp4.4.2 i86QNX6.4.0qcc acpp4.2.4 ppcbe-

QNX6.4.0qcc acpp4.2.4

For -language C++/CLI and C#, valid options for <arch> are:

i86Win32dotnet2.0, x64Win64dotnet2.0, i86Win32dotnet4.0,

x64Win64dotnet4.0

For -language java, valid options for <arch> are:

i86Sol2.9jdk, i86Sol2.10jdk, x64Sol2.10jdk, sparcSol2.9jdk,

sparcSol2.10jdk, sparc64Sol2.10jdk, x64Darwin10gcc4.2.1jdk,

i86Linux2.6gcc3.4.3jdk, x64Linux2.6gcc3.4.5jdk, i86Linux2.6gcc4.1.1jdk,

x64Linux2.6gcc4.1.1jdk, i86Linux2.6gcc4.4.3jdk, x64Linux2.6gcc4.4.3jdk,

i86Linux2.6gcc4.4.5jdk, x64Linux2.6gcc4.4.5jdk, i86Linux2.6gcc4.2.1jdk,

x64Linux2.6gcc4.3.4jdk, i86Linux2.6gcc4.1.2jdk, x64Linux2.6gcc4.1.2jdk,

i86Linux2.6gcc3.4.6jdk, i86RedHawk5.1gcc4.1.2jdk, i86RedHawk5.4gcc4.2.1jdk,

i86Suse10.1gcc4.1.0jdk, x64Suse10.1gcc4.1.0jdk, i86Win32jdk,

x64Win64jdk, ppc7400Lynx4.0.0gcc3.2.2jdk, ppc750Lynx4.0.0gcc3.2.2jdk,

ppc7400Lynx5.0.0gcc3.4.3jdk, i86Lynx4.0.0gcc3.2.2jdk, p5AIX5.3xlc9.0jdk,

64p5AIX5.3xlc9.0jdk

For -language Ada, valid option for <arch> is i86Linux2.6gcc4.1.2

-replace Overwrites any existing output ﬁles. Warning: This removes any

changes you may have made to the original ﬁles.

-debug Generates intermediate ﬁles for debugging purposes.

-corba [client header ﬁle] [-orb <CORBA ORB>] Speciﬁes that you want to

produce CORBA-compliant code.

Use [client header ﬁle] and [-orb <CORBA ORB>] for C++ only. The majority

of code generated is independent of the ORB. However, for some IDL features,

the code generated depends on the ORB. This version of rtiddsgen generates

code compatible with ACE-TAO or JacORB. To pick the ACE TAO version,

use the -orb parameter; the default is ACE TAO1.6.

client header ﬁle: the name of the header ﬁle for the IDL types generated by the

CORBA IDL compiler. This ﬁle will be included in the rtiddsgen type header

ﬁle instead of generating type deﬁnitions.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.59 rtiddsgen 223

CORBA support requires the RTI CORBA Compatibility Kit, an add-

on product that provides a diﬀerent version of rtiddsgen. Please contact

[email protected] for more information.

-optimization Sets the optimization level. (Only applies to C/C++)

0 (default): No optimization.

1: Compiler generates extra code for typedefs but optimizes its use. If the

type that is used is a typedef that can be resolved either to a primitive type

or to another type deﬁned in the same ﬁle, the generated code will invoke

the code of the most basic type to which the typedef can be resolved,

unless the most basic type is an array or a sequence. This level can be

used if the generated code is not expected to be modiﬁed.

2: Maximum optimization. Functionally the same as level 1, but extra

code for typedef is not generated. This level can be used if the typedefs

are only referred by types within the same ﬁle.

-typeSequenceSuﬃx Assigns a suﬃx to the name of the implicit sequence

deﬁned for IDL types. (Only applies to CORBA)

By default, the suﬃx is ’Seq’. For example, given the type ’Foo’ the name of

the implicit sequence will be ’FooSeq’.

-dataReaderSuﬃx Assigns a suﬃx to the name of the DataReader interface.

(Only applies to CORBA)

By default, the suﬃx is ’DataReader’. For example, given the type ’Foo’ the

name of the DataReader interface will be ’FooDataReader’.

-dataWriterSuﬃx Assigns a suﬃx to the name of the DataWriter interface.

(Only applies to CORBA)

By default, the suﬃx is ’DataWriter’. For example, given the type ’Foo’ the

name of the DataWriter interface will be ’FooDataWriter’.

-stringSize Sets the size for unbounded strings. Default: 255 bytes.

-sequenceSize Sets the size for unbounded sequences. Default: 100 elements.

-notypecode: Disables the generation of type code information.

-ppDisable: Disables the preprocessor.

-ppPath <preprocessor executable>: Speciﬁes the preprocessor path. If you

only specify the name of an exe cutable (not a complete path to that executable),

the executable must be found in your Path.

The default value is ”cpp” for non-Windows architectures, ”cl.exe” for Windows

architectures.

If the default preprocessor is not found in your Path and you use - ppPath

to provide its full path and ﬁlename, you must also use -ppOption (described

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

224 Module Documentation

below) to set the following preprocessor options:

If you use a non-default path for cl.exe, you also need to set:

-ppOption /nologo -ppOption /C -ppOption /E -ppOption /X

If you use a non-default path for cpp, you also need to set:

-ppOption -C

-ppOption <option>: Speciﬁes a preprocessor option. This parameter can

be used multiple times to provide the command-line options for the speciﬁed

preprocessor. See -ppPath (above).

-D <name>[=<value>]: Deﬁnes preprocessor macros.

-U <name>: Cancels any previous deﬁnition of name.

-I <directory>: Adds to the list of directories to be searched for type-deﬁnition

ﬁles (IDL, XML, XSD or WSDL ﬁles). Note: A type-deﬁnition ﬁle in one format

cannot include a ﬁle in another format.

-noCopyable: Forces rtiddsgen to put copy logic into the corresponding Type-

Supp ort class rather than the type itself (for Java code generation only).

This option is not compatible with the use of ndds standalone type.jar.

-use42eAlignment: Generates code compliant with RTI Data Distribution

Service 4.2e.

If your RTI Connext application’s data type uses a ’double’,’long long’,’unsigned

long long’, or ’long double’ it will not be backwards compatible with RTI Data

Distribution Service 4.2e applications unless you use the -use42eAlignment ﬂag

when generating code with rtiddsgen.

-enableEscapeChar: Enables use of the escape character ’ ’ in IDL identiﬁers.

With CORB A this option is always enabled.

-convertToXml: Converts the input type-description ﬁle to XML format.

-convertToIdl: Converts the input type-description ﬁle to IDL format.

-convertToXsd: Converts the input type-description ﬁle to XSD format.

-convertToWsdl: Converts the input type-description ﬁle to WSDL format.

-convertToCcl: Converts the input type-description ﬁle to CCL format.

-convertToCcs: Converts the input type-description ﬁle to CCS format.

-expandOctetSeq: When converting to CCS or CCL ﬁles, expand octet se-

quences. The default is to use a blob type.

-expandCharSeq: When converting to CCS or CCL ﬁles, expand char se-

quences. The default is to use a string type.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.59 rtiddsgen 225

-metp: Generates code for the Multi-Encapsulation Type Support (METP)

library.

-version: Prints the version, such as 4.5x. (Does not show ’patch’ revision

number.)

-help: Prints this rtiddsgen usage help.

-verbosity: rtiddsgen verbosity.

1: exceptions

2: exceptions and warnings

3 (default): exceptions, warnings and information

-inputIdl: Indicates that the input ﬁle is an IDL ﬁle, regardless of the ﬁle

extension.

-inputXml: Indicates that the input ﬁle is a XML ﬁle, regardless of the ﬁle

extension.

-inputXsd: Indicates that the input ﬁle is a XSD ﬁle, regardless of the ﬁle

extension.

-inputWsdl: Indicates that the input ﬁle is a WSDL ﬁle, regardless of the ﬁle

extension.

IDLInputFile.idl: File containing IDL descriptions of your data types. If

-inputIdl is not used, the ﬁle must have an .idl extension.

XMLInputFile.xml: File containing XML descriptions of your data types. If

-inputXml is not used, the ﬁle must have an .xml extension.

XSDInputFile.xsd: File containing XSD descriptions of your data types. If

-inputXsd is not used, the ﬁle must have an .xsd extension.

XSDInputFile.wsdl: WSDL ﬁle containing XSD descriptions of your data

types. If -inputWsdl is not used, the ﬁle must have an .wsdl extension.

5.59.2 Description

rtiddsgen takes a language-independent speciﬁcation of the data (in IDL, XML,

XSD or WSDL notation) and generates supporting classes and c ode to distribute

instances of the data over RTI Connext.

To use rtiddsgen, you must ﬁrst write a description of your data types in IDL,

XML, XSD or WSDL format.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

226 Module Documentation

5.59.3 C++ Example

The following is an example generating the RTI Connext type myDataType:

IDL notation

struct myDataType {

long value;

};

XML notation

<?xml version="1.0" encoding="UTF-8"?>

<types xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:noNamespaceSchemaLocation="rti dds topic types.xsd">

</struct>

</types>

XSD notation

<?xml version="1.0" encoding="UTF-8"?>

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:dds="http://www.omg.org/dds"

xmlns:tns="http://www.omg.org/IDL-Mapped/"

targetNamespace="http://www.omg.org/IDL-Mapped/">

<xsd:import namespace="http://www.omg.org/dds" schemaLocation="rti dds topic types common.xsd"/>

<xsd:complexType name="myDataType">

<xsd:sequence>

<xsd:element name="value" minOccurs="1" maxOccurs="1" type="xsd:int"/>

</xsd:sequence>

</xsd:complexType>

</xsd:schema>

WSDL notation

<?xml version="1.0" encoding="UTF-8"?>

<types>

<xsd:schema targetNamespace="http://www.omg.org/IDL-Mapped/">

<xsd:import namespace="http://www.omg.org/dds" schemaLocation="rti dds topic types common.xsd"/>

<xsd:complexType name="myDataType">

<xsd:sequence>

<xsd:element name="value" minOccurs="1" maxOccurs="1" type="xsd:int"/>

</xsd:sequence>

</xsd:complexType>

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.59 rtiddsgen 227

</xsd:schema>

</types>

</definitions>

Assuming the name of the idl ﬁle is myFileName.(idl|xml|xsd|wsdl) then all you

need to do is type:

rtiddsgen myFileName.(idl|xml|xsd|wsdl)

This generates myFileName.cxx, myFileName.h, myFileNamePlugin.cxx, my-

FileNamePlugin.h, myFileNameSupport.cxx and myFileNameSupport.h. By

default, rtiddsgen will not overwrite these ﬁles. You must use the -replace

argument to do that.

5.59.4 IDL Language

In the IDL language, data types are described in a fashion almost identical to

structures in ”C.” The complete description of the language can be found at the

OMG website.

rtiddsgen does not support the full IDL language.

For detailed information about the IDL support in RTI Connext see Chapter 3

in the User’s Manual.

The supported IDL types are:

char

wchar

octet

short

unsigned s hort

long

unsigned long

long long

unsigned long long

ﬂoat

double

long double

boolean

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

228 Module Documentation

bounded string

unbounded string

bounded wstring

unbounded wstring

enum

typedef

struct

valuetypes (limited support)

union

sequences

unbounded sequences

arrays

array of sequences

constant

The following non-IDL types are also supported:

bitﬁeld

valued enum

Use of Unsupported Types in an IDL File

You may include unsupported data types in the IDL ﬁle. rtiddsgen does not

consider this an error. This allows you to use types that are deﬁned in non-

IDL languages with either hand-written or non-rtiddsgen written plug-ins. For

example, the following is allowable:

//@copy #include "Bar.h"

//@copy #include "BarHandGeneratedPlugin.h"

struct Foo {

short height;

Bar barMember;

};

In the above case, Bar is deﬁned externally by the user.

Multiple Types in a Single File

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.59 rtiddsgen 229

You can specify multiple types in a single IDL ﬁle. This can simplify manage-

ment of ﬁles in your distributed program.

Use of Directives in an IDL File

The following directives can be used in your IDL ﬁle: Note: Do not put a space

between the slashes and the @ sign. Note: Directives are case-sensitive (for

example: use key, not Key).

//@key Speciﬁes that the ﬁeld declared just before this directive in the

enclosing structure is part of the key. Any number of a structure’s ﬁelds

may be declared part of the key.

//@copy Copies a line of text (verbatim) into the generated code (for all

languages). The text is copied into all the type-speciﬁc ﬁles generated by

rtiddsgen exc ept the examples.

//@copy-declaration Like //@copy, but only copies the text into the ﬁle

where the type is declared (<type>.h for C++/C, or <type>.java for

Java).

//@copy-c Like //@copy, but for C++/C-only code.

//@copy-c-declaration Like //@copy-declaration, but for C++/C-only

code.

//@copy-java Like //@copy, but for Java-only code.

//@copy-java-begin Copies a line of text at the beginning of all the Java

ﬁles generated for a type. The directive only applies to the ﬁrst type that

is immediately below in the IDL ﬁle.

//@copy-java-declaration Like //@copy-declaration, but for Java-only

code.

//@copy-java-declaration-begin Like //@copy-java-begin but only copies

the text into the ﬁle where the type is declared.

//@copy-ada Like //@copy, but for Ada-only code.

//@copy-ada-begin Like //@copy-java-begin, but for Ada-only code.

//@copy-ada-declaration Like //@copy-declaration, but for Ada-only

code.

//@copy-ada-declaration-b e gin Like //@copy-java-declaration, but for

Ada-only c ode.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

230 Module Documentation

//@resolve-name [true|false] Sp ec iﬁes whether or not rtiddsgen should re-

solve the scope of a type. If this directive is not present or is set to true,

rtiddsgen resolves the scope. Otherwise rtiddsgen delegates the resolution

of a type to the user.

//@top-level [true|false] Speciﬁes whether or not rtiddsgen should generate

type-support code for a particular struct or union. The default is true.

5.59.5 XML Language

The data types can be described using XML.

RTI Connext provides DTD and XSD ﬁles that describe the XML format.

The DTD deﬁnition of the XML elements can be

found in ../../../resource/dtd/rti dds topic types.dtd” under

<NDDSHOME>/resource/rtiddsgen/schema.

The XSD deﬁnition of the XML elements can be

found in ../../../resource/xsd/rti dds topic types.xsd” under

<NDDSHOME>/resource/rtiddsgen/schema.

The XML validation p erformed by rtiddsgen always uses the DTD deﬁnition.

If the <!DOCTYPE> tag is not present in the XML ﬁle, rtiddsgen will look for

the DTD document under <NDDSHOME>/resource/rtiddsgen/schema. Oth-

erwise, it will use the location speciﬁed in <!DOCTYPE>.

For detailed information about the mapping between IDL and XML, see Chapter

3 in the User’s Manual.

5.59.6 XSD Language

The data types can b e desc ribed using XML schemas (XSD ﬁles). The XSD

speciﬁcation is based on the standard IDL to WSDL mapping described in the

OMG document CORBA to WSDL/SOAP Interworking Specification

For detailed information about the mapping between IDL and XML see Chapter

3 in the User’s Manual.

5.59.7 WSDL Language

The data types can be described using XML schemas contained in WSDL

ﬁles. The XSD speciﬁcation is based on the standard IDL to WSDL map-

ping described in the OMG document CORBA to WSDL/SOAP Interworking

Specification

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.59 rtiddsgen 231

For detailed information about the mapping between IDL and XML see Chapter

3 in the User’s Manual.

5.59.8 Using Generated Types Without RTI Connext

(Standalone)

You can use the generated type-speciﬁc source and header ﬁles without linking

the RTI Connext libraries or even including the RTI Connext header ﬁles. That

is, the generated ﬁles for your data types can be used standalone.

The directory <NDDSHOME>/resource/rtiddsgen/standalone contains the

helper ﬁles required to work in standalone mode:

include: header and templates ﬁles for C/C++.

src: source ﬁles for C/C++.

class: Java jar ﬁle.

Using Standalone Types in C

The generated ﬁles that can be used standalone are:

<idl ﬁle name>.c : Types source ﬁle

<idl ﬁle name>.h : Types header ﬁle

You cannot use the type plug-in (<idl ﬁle>Plugin.c <idl ﬁle>Plugin.h) or the

type support (<idl ﬁle>Support.c <idl ﬁle>Support.h) code standalone.

To use the rtiddsgen-generated types in a standalone manner:

Include the directory <NDDSHOME>/resource/rtiddsgen/standalone/include

in the list of directories to be searched for header ﬁles.

Add the source ﬁles ndds standalone type.c and <idl ﬁle name>.c to your

project.

Include the ﬁle <idl ﬁle name>.h in the source ﬁles that will use the

generated types in a standalone way.

Compile the project using the two following preprocessor deﬁnitions:

– NDDS STANDALONE TYPE

– The deﬁnition for your platform: RTI VXWORKS, RTI QNX, RTI -

WIN32, RTI INTY, RTI LYNX or RTI UNIX

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

232 Module Documentation

Using Standalone Types in C++

The generated ﬁles that can be used standalone are:

<idl ﬁle name>.cxx : Types source ﬁle

<idl ﬁle name>.h : Types header ﬁle

You cannot use the type plugin (<idl ﬁle>Plugin.cxx <idl ﬁle>Plugin.h) or the

type support (<idl ﬁle>Support.cxx <idl ﬁle>Support.h) code standalone.

To use the generated types in a standalone manner:

Include the directory <NDDSHOME>/resource/rtiddsgen/standalone/include

in the list of directories to be searched for header ﬁles.

Add the source ﬁles ndds standalone type.cxx and <idl ﬁle name>.cxx to

your project.

Include the ﬁle <idl ﬁle name>.h in the source ﬁles that will use the

generated types in a standalone way.

Compile the project using the two following preprocessor deﬁnitions:

– NDDS STANDALONE TYPE

– The deﬁnition for your platform: RTI VXWORKS, RTI QNX, RTI -

WIN32, RTI INTY, RTI LYNX or RTI UNIX

Standalone Types in Java

The generated ﬁles that can be used standalone are:

<idl type>.java

<idl type>Seq.java

You cannot use the type code (<idl ﬁle>TypeCode.java), the type support

(<idl type>TypeSupp ort.java), the data reader (<idl ﬁle>DataReader.java) or

the data writer code (<idl ﬁle>DataWriter.java) standalone.

To use the generated types in a standalone manner:

Include the ﬁle ndds standalone type.jar in the classpath of your project.

Compile the project using the standalone types ﬁles (<idl type>.java <idl

type>Seq.java).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.60 rtiddsping 233

5.60 rtiddsping

Sends or receives simple messages using RTI Connext. The rtiddsping utility

uses RTI Connext to send and receive preconﬁgured ”Ping” messages to other

rtiddsping applications which can be running in the same or diﬀerent computers.

The rtiddsping utility can used to test the network and/or computer conﬁgura-

tion and the environment settings that aﬀect the operation of RTI Connext.

Usage

rtiddsping [-help] [-version]

[-domainId <domainId>] ... defaults to 0

[-index <NN>] ... defaults to -1 (auto)

[-appId <ID>] ... defaults to a middleware-selected value

[-Verbosity <NN>] ... can be 0..5

[-peer <PEER>] ... PEER format is NN@TRANSPORT://ADDRESS

[-discoveryTTL <NN>] ... can be 0..255

[-transport <MASK>] ... defaults to DDS TRANSPORTBUILTIN MASK DEFAULT

[-msgMaxSize <SIZE>] ... defaults to -1 (transport default)

[-shmRcvSize <SIZE>] ... defaults to -1 (transport default)

[-deadline <SS>] ... defaults to -1 (no deadline)

[-durability <TYPE>] ... TYPE can be VOLATILE or TRANSIENT LOCAL

[-multicast <ADDRESS>] ... defaults to no multicast

[-numSamples <NN>] ... defaults to infinite

[-publisher] ... this is the default

[-queueSize <NN>] ... defaults to 1

[-reliable] ... defaults to best-efforts

[-sendPeriod <SS>] ... SS is in seconds, defaults to 1

[-subscriber]

[-timeFilter <SS>] ... defaults to 0 (no filter)

[-timeout <SS>] ... SS is in seconds, defaults to infinite

[-topicName <NAME>] ... defaults to PingTopic

[-typeName <NAME>] ... defaults to PingType

[-useKeys <NN>] ... defaults to PingType

[-qosFile <file>]

[-qosProfile <lib::prof>]

Example: rtiddsping -domainId 3 -publisher -numSamples 100

VxWorks Usage

rtiddsping "[<options>]"

The options use the same syntax as above.

Example rtiddsping "-domainId 3 -publisher -numSamples 100"

If the stack of the shell is not large enough to run rtiddsping, use "taskSpawn":

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

234 Module Documentation

taskSpawn <name>,<priority>,<taskspawn options>,<stack size in bytes>,rtiddsping,"[\<options\>]"

The options use the same syntax as above.

Example taskSpawn "rtiddsping",100,0x8,50000,rtiddsping,"-domainId 3 -publisher -numSamples 100"

Options:

-help Prints a help message and exits.

-version Prints the version and exits.

-Verbosity <NN> Sets the verbosity level. The range is 0 to 5.

0 has minimal output and does not echo the fact that data is being sent or

received.

1 prints the most relevant statuses, including the sending and receiving of data.

This is the default.

2 prints a summary of the parameters that are in use and echoes more detailed

status messages.

3-5 Mostly aﬀects the verbosity used by the internal RTI Connext modules that

implement rtiddsping. The output is not always readable; its main purp ose is

to provide information that may be useful to RTI’s support team.

Example: rtiddsping -Verbosity 2

-domainId <NN>

Sets the domain ID. The valid range is 0 to 100.

Example: rtiddsping -domainId 31

-appId <ID>

Sets the application ID. If unspeciﬁed, the system will pick one automatically.

This option is rarely used.

Example: rtiddsping -appId 34556

-index <NN>

Sets the participantIndex. If participantIndex is not -1 (auto), it must be dif-

ferent than the one used by all other applications in the same computer and

domainId. If this is not respected, rtiddsping (or the application that starts

last) will get an initialization error.

Example: rtiddsping -index 2

-peer <PEER>

Speciﬁes a PEER to be used for discovery. Like any RTI Connext application, it

defaults to the se tting of the environment variable NDDS DISCOVERY PEERS

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.60 rtiddsping 235

or a preconﬁgured multicast address if the environment is not set.

The format used for PEER is the same one used for NDDS DISCOVERY -

PEERS and is described in detail in NDDS DISCOVERY PEERS (p. 388).

A brief summary follows:

The general format is: NN@TRANSPORT://ADDRESS where:

ADDRESS is an address (in name form or using the IP notation

xxx.xxx.xxx.xxx). ADDRESS may be a multicast address.

TRANSPORT represents the kind of transport to use and NN is the max-

imum participantIndex expected at that location. NN can be omitted and

it is defaulted to ’4’

Valid settings for TRANSPORT are ’udpv4’ and ’shmem’. The default

setting if the transport is omitted is ’udpv4’.

ADDRESS cannot be omitted if the ’-peer’ option is speciﬁed.

The -peer option may be repeated to specify multiple peers.

Example: rtiddsping -peer 10.10.1.192 -peer mars -peer 4@pluto

-discoveryTTL <TTL>

Sets the TTL (time -to-live) used for multicast discovery. If not speciﬁed, it

defaults to the built-in RTI Connext default.

The valid range is 0 to 255. The value ’0’ limits multicast to the node itself

(i.e., can only discover applications running on the same computer). The value

’1’ limits multicast discovery to computers on the same subnet. Values higher

than 1 generally indicate the maximum number of routers that may be traversed

(although some routers may be conﬁgured diﬀerently).

Example: rtiddsping -discoveryTTL 16

-transport <MASK>

A bit-mask that sets the enabled builtin transports. If not speciﬁed, the default

set of transports is used (UDPv4 + shmem). The bit values are: 1=UDPv4,

2=shmem, 8=UDPv6.

-msgMaxSize <SIZE>

Conﬁgure the maximum message size allowed by the installed transports. This

is needed if you are using rtiddsping to communicate with an application that

has set these transport parameters to larger than default values.

-shmRcvSize <SIZE>

Increase the shared memory receive-buﬀer size. This is needed if you are using

rtiddsping to communicate with an application that has set these transp ort

parameters to larger than default values.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

236 Module Documentation

-deadline <SS>

This option only applies if the ’-subscriber’ option is also speciﬁed.

Sets the DEADLINE QoS for the subscriptions made by rtiddsping.

Note that this may cause the subscription QoS to be incompatible with the

publisher if the publisher did not specify a sendPeriod greater than the deadline.

If the QoS is incompatible, rtiddsping will not receive updates.

Each time a deadline is detected, rtiddsping will print a mes sage indicating the

number of deadlines received so far.

Example: rtiddsping -deadline 3.5

-durability <TYPE>

Sets the DURABILITY QoS used for publishing or subscribing. Valid settings

are: VOLATILE and TRANSIENT LOCAL (default). The eﬀect of this setting

can only be observed when it is used in in conjunction with reliability and a

queueSize larger than 1. If all these conditions are met, a late-joining subscriber

will be able to see up to queueSize samples that were previously written by the

publisher.

Example: rtiddsping -durability VOLATILE

-multicast <ADDRESS>

This option only applies if the ’-subscriber’ option is also speciﬁed.

Conﬁgures ping to receive messages over multicast. The <ADDRESS> param-

eter indicates the address to use. ADDRESS must be in the valid range for mul-

ticast addresses. For IP version 4 the valid range is 224.0.0.1 to 239.255.255.255

Example: rtiddsping -multicast 225.1.1.1

-numSamples <NN>

Sets the number of samples that will be sent by rtiddsping. After those samples

are sent, rtiddsping will exit. messages.

Example: rtiddsping -numSamples 10

-publisher

Causes rtiddsping to send ping messages. This is the default.

Example: rtiddsping -publisher

-queueSize <NN>

Speciﬁes the maximal number of samples to hold in the queue. In the case of the

publisher, it aﬀects the samples that are available for a late-joining subscriber.

Example: rtiddsping -queueSize 100

-reliable

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.60 rtiddsping 237

Conﬁgures the RELIABILITY QoS for publishing or subscribing. The default

setting (if -reliable is not used) is BEST EFFORT

Example: rtiddsping -reliable

-sendPeriod <SS>

Sets the period (in seconds) at which rtiddsping sends the messages.

Example: rtiddsping -s endPeriod 0.5

-subscriber

Causes rtiddsping to listen for ping messages. This option cannot be speciﬁed

if ’-publisher’ is also speciﬁed.

Example: rtiddsping -s ubscriber

-timeFilter <SS>

This option only applies if the ’-subscriber’ option is also speciﬁed.

Sets the TIME BASED FILTER QoS for the subscriptions made by rtiddsping.

This QoS causes RTI Connext to ﬁlter out messages that are published at a rate

faster than what the ﬁlter duration permits. For example, if the ﬁlter duration

is 10 seconds, messages will be printed no faster than once every 10 seconds.

Example: rtiddsping -time Filter 5.5

-timeout <SS>

This option only applies if the ’-subscriber’ option is also speciﬁed.

Sets a timeout (in seconds) that will cause rtiddsping to exit if no samples are

received for a duration that exceeds the timeout.

Example: rtiddsping -time out 30

-topicName <NAME>

Sets the topic name used by rtiddsping. The default is ’RTIddsPingTopic’. To

communicate, both the publisher and subscriber must specify the same topic

name.

Example: rtiddsping -topicName Alarm

-typeName <NAME>

Sets the type name used by rtiddsping. The default is ’RTIddsPingType’. To

communicate, both publisher and subscriber must specify the same type name.

Example: rtiddsping -typeName AlarmDescription

-useKeys <NN>

This option cause s rtiddsping to use a topic whose data contains a key. The

value of the NN parameter indicates the number of diﬀerent data objects (each

identiﬁed by a diﬀerent value of the key) that will be published by rtiddsping.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

238 Module Documentation

The value of NN only aﬀects the publishing behavior. However NN still needs

to be speciﬁed when the -useKeys option is used with the -subscriber option.

For communication to occur, both the publisher and subscriber must agree on

whether the topic that they publish/subscribe contains a key. Consequently, if

you specify the -useKeys parameter for the publisher, you must do the same

with the subscriber. Otherwise communication will not be stablished.

Example: rtiddsping -use Keys 20

-qosFile <ﬁle>

Allow you to specify additional QoS XML settings using url proﬁle. For more

information on the syntax, see Chapter 15 in the RTI Connext User’s Manual.

Example: rtiddsping -qosFile /home/user/QoSProﬁleFile.xml

-qosProﬁle <lib::prof>

This option speciﬁes the library name and proﬁle name that the tool should use.

QoS settings

rtiddsping is conﬁgured internally using a special set of QoS settings in a proﬁle

called InternalPingLibrary::Inte rnalPingProﬁle. This is the default proﬁle un-

less a proﬁle called DefaultPingLibrary::DefaultPingProﬁle is found. You can

use the command-line option -qosProﬁle to tell rtiddsping to use a diﬀerent

lib::proﬁle instead of DefaultPingLibrary::DefaultPingProﬁle. Like all the other

RTI Connext applications, rtiddsping loads all the proﬁles speciﬁed using the

environment variable NDDS QOS PROFILES or the ﬁle named USER QOS -

PROFILES found in the current working directory.

The QoS settings used internally are available in the ﬁle RTIDDSSPING QOS -

PROFILES.example.xml.

Description

The usage depends on the operating system from which rtiddsping is executed.

Examples for UNIX, Linux, and Windows Systems

On UNIX, Linux, Windows and other operating systems that have a shell, the

syntax matches the one of the regular commands available in the shell. In the

examples below, the string ’shell prompt>’ represents the prompt that the shell

prints and are not part of the command that must be typed.

shell prompt> rtiddsping -domainId 3 -publisher -numSamples 100

shell prompt> rtiddsping -domainId 5 -subscriber -timeout 20

shell prompt> rtiddsping -help

VxWorks examples:

On VxWorks systems, the libraries libnddscore.so, libnddsc.so and libnddscpp.so

must ﬁrst be loaded. The rtiddsping command must be typed to the VxWorks

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.60 rtiddsping 239

shell (either an rlogin shell, a target-server shell, or the serial line prompt). The

arguments are passed embedded into a single string, but otherwise have the

same syntax as for Unix/Windows. In the Unix, Linux, Windows and other

operating systems that have a shell, the syntax matches the one of the regular

commands available in the shell. In the examples below, the string ’vxworks

prompt>’ represents the prompt that the shell prints and are not part of the

command that must be typed.

vxworks prompt> rtiddsping "-domainId 3 -publisher -numSamples 100"

vxworks prompt> rtiddsping "-domainId 5 -subscriber -timeout 20"

vxworks prompt> rtiddsping "-help"

or, alternatively (to avoid overflowing the stack):

vxworks prompt> taskSpawn "rtiddsping", 100, 0x8, 50000, rtiddsping, "-domainId 3 -publisher -numSamples 100"

vxworks prompt> taskSpawn "rtiddsping", 100, 0x8, 50000, rtiddsping, "-domainId 5 -subscriber -timeout 20"

vxworks prompt> taskSpawn "rtiddsping", 100, 0x8, 50000, rtiddsping, "-help"

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

240 Module Documentation

5.61 rtiddsspy

Debugging tool which receives all RTI Connext communication. The rtiddsspy

utility allows the user to monitor groups of publications available on any RTI

Connext domain.

Note: If you have more than one DataWriter for the same Topic, and these

DataWriters have diﬀerent settings for the Ownership QoS, then rtiddsspy will

only re ceive (and thus report on) the samples from the ﬁrst DataWriter.

To run rtiddsspy, like any RTI Connext application, you must have the NDDS -

DISCOVERY PEERS environment variable that deﬁnes your RTI Connext do-

main; otherwise you must specify the peers as command line parameters.

Usage

rtiddsspy [-help] [-version]

[-domainId <domainId>] ... def aults to 0

[-index <NN>] ... defaults to -1 (auto)

[-appId <ID>] ... defaults to a middleware-selected value

[-Verbosity <NN>] ... can be 0..5

[-peer <PEER>] ... PEER format is NN@TRANSPORT://ADDRESS

[-discoveryTTL <NN>] ... can be 0..255

[-transport <MASK>] ... defaults to DDS TRANSPORTBUILTIN MASK DEFAULT

[-msgMaxSize <SIZE>] ... defaults to -1 (transport default)

[-shmRcvSize <SIZE>] ... defaults to -1 (transport default)

[-tcMaxSize <SIZE>] ... defaults to 4096

[-hOutput]

[-deadline <SS>] ... defaults to -1 (no deadline)

[-history <DEPTH>] ... defaults to 8192

[-timeFilter <SS>] ... defaults to 0 (no filter)

[-useFirstPublicationQos]

[-showHandle]

[-typeRegex <REGEX>] ... defaults to "*"

[-topicRegex <REGEX>] ... defaults to "*"

[-typeWidth <WIDTH>] ... can be 1..255

[-topicWidth <WIDTH>] ... can be 1..255

[-truncate]

[-printSample]

[-qosFile <file>]

[-qosProfile <lib::prof>]

Example: rtiddsspy -domainId 3 -topicRegex "Alarm*"

VxWorks Usage

rtiddsspy "[<options>]"

The options use the same syntax as above.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.61 rtiddsspy 241

Example rtiddsspy "-domainId 3 -topicRegex Alarm*"

rtiddsspy requires about 25 kB of stack. If the stack size of the shell from which it is invoked is not large enough, use "taskSpawn":

taskSpawn <name>, <priority>, <taskspawn options>, <stack size in bytes>, rtiddsspy, "[\<options\>]"

The options use the same syntax as above.

Example taskSpawn "rtiddsspy", 100, 0x8, 50000, rtiddsspy, "-domainId 3 -topicRegex Alarm*"

Options:

-help Prints a help message and exits.

-version Prints the version and exits.

-Verbosity <NN> Sets the verbosity level. The range is 0 to 5.

0 has minimal output and does not echo the fact that data is being sent or

received.

1 prints the most relevant statuses, including the sending and receiving of data.

This is the default.

2 prints a summary of the parameters being used and echoes more detailed

status messages.

3-5 Mostly aﬀect the verbosity used by the internal RTI Connext modules that

implement rtiddsspy. The output is not always readable; its main purpose is to

provide information that may be useful to RTI’s support team.

Example: rtiddsspy -Verbosity 2

-domainId <NN>

Sets the domain ID. The valid range is 0 to 100.

Example: rtiddsspy -domainId 31

-appId <ID>

Sets the application ID. If unspeciﬁed, the system will pick one automatically.

This option is rarely used.

Example: rtiddsspy -appId 34556

-index <NN>

Sets the participantIndex. If participantIndex is not -1 (auto), it must be dif-

ferent than the one used by all other applications in the same computer and

domainId. If this is not respected, rtiddsspy (or the application that starts last)

will get an initialization error.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

242 Module Documentation

Example: rtiddsspy -index 2

-peer <PEER>

Speciﬁes a PEER to be used for discovery. Like any RTI Connext application, it

defaults to the se tting of the environment variable NDDS DISCOVERY PEERS

or a preconﬁgured multicast address if the environment is not set.

The format used for PEER is the same used for the NDDS DISCOVERY -

PEERS and is described in detail in NDDS DISCOVERY PEERS (p. 388).

A brief summary follows:

The general format is: NN@TRANSPORT://ADDRESS where:

ADDRESS is an address (in name form or using the IP notation

xxx.xxx.xxx.xxx). ADDRESS may be a multicast address.

TRANSPORT represents the kind of transport to use and NN is the max-

imum participantIndex expected at that location. NN can be omitted and

it is defaulted to ’4’

Valid settings for TRANSPORT are ’udpv4’ and ’shmem’. The default

setting if the transport is omitted is ’udpv4’

ADDRESS cannot be omitted if the ’-peer’ option is speciﬁed.

The -peer option may be repeated to specify multiple peers.

Example: rtiddsspy -peer 10.10.1.192 -peer mars -peer 4@pluto

-discoveryTTL <TTL>

Sets the TTL (time -to-live) used for multicast discovery. If not speciﬁed, it

defaults to the built-in RTI Connext default.

The valid range is 0 to 255. The value ’0’ limits multicast to the node itself (i.e.

can only discover applications running on the same computer). The value ’1’

limits multicast discovery to computers on the same subnet. Settings greater

than 1 generally indicate the maximum number of routers that may be traversed

(although some routers may be conﬁgured diﬀerently).

Example: rtiddsspy -discoveryTTL 16

-transport <MASK>

SPe ciﬁes a bit-mask that sets the enabled builtin transports. If not speciﬁed,

the default set of transports is used (UDPv4 + shmem). T he bit values are:

1=UDPv4, 2=shmem , 8=UDPv6.

-msgMaxSize <SIZE>

Conﬁgures the maximum message size allowed by the installed transports. This

is needed if you are using rtiddsspy to communicate with an application that

has set these transport parameters to larger than default values.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.61 rtiddsspy 243

-shmRcvSize <SIZE>

Increases the shared memory rec eive-buﬀer size. This is needed if you are us-

ing rtiddsspy to communicate with an application that has set these transport

parameters to larger than default values.

-tcMaxSize <SIZE>

Conﬁgures the maximum size, in bytes, of a received type code.

-hOutput

Prints information on the output format used by rtiddsspy.

This option prints an explanation of the output and then exits.

Example: rtiddsspy -hOutput

-deadline <SS>

Sets the requested DEADLINE QoS for the subscriptions made by rtiddsspy.

Note that this may cause the subscription QoS to be incompatible with the

publisher if the publisher did not specify an oﬀered deadline that is greater or

equal to the one requested by rtiddsspy. If the QoS is incompatible rtiddsspy

will not receive updates from that writer.

Each time a deadline is detected rtiddsspy will print a message that indicates

the number of deadlines received so far.

Example: rtiddsspy -deadline 3.5

-timeFilter <SS>

Sets the TIME BASED FILTER QoS for the subscriptions made by rtiddsspy.

This QoS causes RTI Connext to ﬁlter-out messages that are published at a rate

faster than what the ﬁlter duration permits. For example if the ﬁlter duration

is 10 seconds, messages will be printed no faster than once each 10 seconds.

Example: rtiddsspy -timeFilter 10.0

-history <DEPTH>

Sets the HISTORY depth QoS for the subscriptions made by rtiddsspy.

This may be relevant if the publisher has batching turned on, or if the -

useFirstPublicationQos option is used that is causing a reliable or durable sub-

scription to be created.

Example: rtiddsspy -history 1

-useFirstPublicationQos

Sets the RELIABILITY and DURABILITY QoS of the s ubscription based on

the ﬁrst discovered publication of that topic.

See also:

DDS WireProtocolQosPolicy::participant id (p. 1063)

NDDSTransportSupport::set builtin transport property()

(p. 1564)

5.65.5 Creating and Registering Shared Memory Trans-

port Plugin

RTI Connext can implicitly create this plugin and register with the DDS-

DomainParticipant (p. 1139) if this transport is speciﬁed in DDS -

TransportBuiltinQosPolicy (p. 969).

To specify the properties of the builtin shared memory transport that is implic-

itly registered, you can either:

call NDDSTransportSupport::set builtin transport property

(p. 1564) or

specify the pre-deﬁned property names in DDS PropertyQosPolicy

(p. 834) associated with the DDSDomainParticipant (p. 1139). (see

Shared Memory Transport Property Names in Property QoS

Policy of Domain Participant (p. 261)).

Builtin transport plugin properties speciﬁed in DDS PropertyQosPolicy

(p. 834) always overwrite the ones speciﬁed through NDDSTransportSup-

port::set builtin transport property() (p. 1564). The default value is as-

sumed on any unspeciﬁed property. Note that all properties should be se t before

the transport is implicitly created and registered by RTI Connext. See Built-in

Transport Plugins (p. 136) for details on when a builtin transport is regis-

tered.

To explicitly create an instance of this plugin, NDDS Transport Shmem -

new() (p. 262) should be called. The instance s hould be registered with RTI

Connext, see NDDSTransportSupport::register transport (p. 1560). In

some conﬁgurations, you m ay have to disable the builtin shared memory trans-

port plugin instance (DDS TransportBuiltinQosPolicy (p. 969), DDS -

TRANSPORTBUILTIN SHMEM (p. 398)), to avoid port conﬂicts with

the newly created plugin instance.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.65 Shared Memory Transport 261

5.65.6 Shared Memory Transp ort Property Names in

Property QoS Policy of Domain Participant

The following table lists the predeﬁned property names that can be set in the

DDS PropertyQosPoli cy (p. 834) of a DDSDomainParticipant (p. 1139)

to conﬁgure the builtin shared memory transport plugin.

5.65.7 Deﬁne Documentation

5.65.7.1 #deﬁne NDDS TRANSPORT CLASSID SHMEM (2)

Builtin Shared-Memory Transport-Plugin class ID.

5.65.7.2 #deﬁne NDDS TRANSPORT SHMEM ADDRESS BIT -

COUNT (0)

Default value of NDDS Transport Property t::address bit count

(p. 1524).

5.65.7.3 #deﬁne NDDS TRANSPORT SHMEM -

PROPERTIES BITMAP DEFAULT (

NDDS TRANSPORT PROPERTY BIT BUFFER -

ALWAYS LOANED )

Default value of NDDS Transport Property t::properties bitmap

(p. 1524).

5.65.7.4 #deﬁne NDDS TRANSPORT SHMEM GATHER -

SEND BUFFER COUNT MAX DEFAULT (1024)

Default value of NDDS Transport Property t: :gather send buﬀer -

count max (p. 1525).

5.65.7.5 #deﬁne NDDS TRANSPORT SHMEM MESSAGE -

SIZE MAX DEFAULT (9216)

Default value of NDDS Transport Property t::message size max

(p. 1525).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

262 Module Documentation

5.65.7.6 #deﬁne NDDS TRANSPORT SHMEM RECEIVED -

MESSAGE COUNT MAX DEFAULT (32)

Default value of NDDS Transport Shmem Property t::received -

message count max (p. 1530).

5.65.7.7 #deﬁne NDDS TRANSPORT SHMEM RECEIVE -

BUFFER SIZE DEFAULT

Value:

(NDDS_TRANSPORT_SHMEM_RECEIVED_MESSAGE_COUNT_MAX_DEFAULT * \

NDDS_TRANSPORT_SHMEM_MESSAGE_SIZE_MAX_DEFAULT / 4)

Default value of NDDS Transport Shmem Property t::receive buﬀer -

size (p. 1531).

5.65.7.8 #deﬁne NDDS TRANSPORT SHMEM PROPERTY -

DEFAULT

Use this to initialize stack variable.

5.65.8 Function Documentation

5.65.8.1 NDDS Transp ort Plugin∗ NDDS Transport Shmem new

(const struct NDDS Transport Shmem Property t ∗

property in)

Create a new shmem process transport.

An application may create multiple transports, pos sibly for use in diﬀerent

domains.

Parameters:

property in <<in>> ( p. 200) Desired behavior of this transport. May

be NULL for default property. The transport plugin can only support

one unicast receive interface; therefore the interface selection lists are

ignored.

Returns:

handle to a Shmem inter-process Transport Plugin on succ ess

NULL on failure.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.65 Shared Memory Transport 263

5.65.8.2 NDDS Transp ort Plugin∗ NDDS Transport Shmem create

(NDDS Transport Address t ∗ default network -

address out, const struct DDS PropertyQosPolicy ∗

property in)

Create a new shmem process transport, using PropertyQosPolicy.

An application may create multiple transports, pos sibly for use in diﬀerent

domains.

Parameters:

default network address out <<out>> ( p. 200) Network address to

be used when registering the transport.

property in <<in>> ( p. 200) Desired behavior of this transport. May

be NULL for default property. The transport plugin can only support

one unicast receive interface; therefore the interface selection lists are

ignored.

Returns:

handle to a Shmem inter-process Transport Plugin on succ ess

NULL on failure.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

264 Module Documentation

Name Descriptions

dds.transp ort.shmem.builtin.parent.address -

bit count

See NDDS Transport -

Property t::address bit count

(p. 1524)

dds.transp ort.shmem.builtin.parent.properties -

bitmap

See NDDS Transport -

Property t::properties bitmap

(p. 1524)

dds.transp ort.shmem.builtin.parent.gather -

send buﬀer count max

See NDDS Transport -

Property t::gather send -

buﬀer count max

(p. 1525)

dds.transp ort.shmem.builtin.parent.message -

size max

See NDDS Transport -

Property t::message size max

(p. 1525)

dds.transp ort.shmem.builtin.parent.allow -

inte rfaces

See NDDS Transport -

Property t::allow int erfaces list

(p. 1526) and

NDDS Transport Property -

t::allow interfaces li st length

(p. 1526).

Interfaces should be speciﬁed as

comma-separated strings, with each

comma delimiting an interface. For

example: 127.0.0.1,eth0

dds.transp ort.shmem.builtin.parent.deny -

inte rfaces

See NDDS Transport -

Property t::deny int erfaces list

(p. 1526) and

NDDS Transport Property -

t::deny interfaces li st length

(p. 1527).

Interfaces should be speciﬁed as

comma-separated strings, with each

comma delimiting an interface. For

example: 127.0.0.1,eth0

dds.transp ort.shmem.builtin.parent.allow -

multicast interfaces

See

NDDS Transport Property -

t::allow multicast interfaces list

(p. 1527) and NDDS Transport -

Property t::allow mul ticast -

interfaces list length

(p. 1528).

Interfaces should be speciﬁed as

comma-separated strings, with each

comma delimiting an interface. For

example: 127.0.0.1,eth0

dds.transp ort.shmem.builtin.parent.deny -

multicast interfaces

See

NDDS Transport Property -

t::deny multicast interfaces list

(p. 1528) and NDDS Transport -

Property t::deny mul ticast -

interfaces list length (p. 1528).

Interfaces should be speciﬁed as

comma-separated strings, with each

comma delimiting an interface. For

example: 127.0.0.1,eth0

dds.transp ort.shmem.builtin.received -

message count max

See NDDS Transport Shmem -

Property t::received message -

count max

(p. 1530)

dds.transp ort.shmem.builtin.receive -

buﬀer size

See NDDS Transport Shmem -

Property t::receive buﬀer size

(p. 1531)

Table 5.8: Property Strings for Shared Memory Transport

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.66 UDPv4 Transport 265

5.66 UDPv4 Transport

Built-in transport plug-in using UDP/IPv4 (NDDS TRANSPORT -

CLASSID UDPv4 (p. 268)).

Classes

struct NDDS Transport UDPv4 Property t

Conﬁgurable IPv4/UDP Transport-Pl ugin properties.

Deﬁnes

#deﬁne NDDS TRANSPORT CLASSID UDPv4 (1)

Builtin IPv4 UDP/IP Transport-Plugin class ID.

#deﬁne NDDS TRANSPORT UDPV4 ADDRESS BIT -

COUNT (32)

Default value of NDDS Transport Property t::address bit count

( p. 1524).

#deﬁne NDDS TRANSPORT UDPV4 PROPERTIES -

BITMAP DEFAULT (0)

Default value of NDDS Transport Property t::properties bitmap

( p. 1524).

#deﬁne NDDS TRANSPORT UDPV4 GATHER SEND -

BUFFER COUNT MAX DEFAULT (16)

Default value of NDDS Transport Property t::gather send buﬀer -

count max ( p. 1525).

#deﬁne NDDS TRANSPORT UDPV4 SOCKET BUFFER -

SIZE OS DEFAULT (-1)

Used to specify that os default be used to specify socket buﬀer size.

#deﬁne NDDS TRANSPORT UDPV4 MESSAGE SIZE -

MAX DEFAULT (9216)

Default value of NDDS Transport Prope rty t::message size max

( p. 1525).

#deﬁne NDDS TRANSPORT UDPV4 MULTICAST TTL -

DEFAULT (1)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

266 Module Documentation

Default value of NDDS Transport UDPv4 Property t::multicast ttl

( p. 1536).

#deﬁne NDDS TRANSPORT UDPV4 BLOCKING NEVER

Value for NDDS Transport UDPv4 Property t::send blocking

( p. 1539) to specify non-blocking sockets.

#deﬁne NDDS TRANSPORT UDPV4 BLOCKING ALWAYS

[default] Value for NDDS Transport UDPv4 Property t::send -

blocking ( p. 1539) to specify blocking sockets.

#deﬁne NDDS TRANSPORT UDPV4 BLOCKING -

DEFAULT NDDS TRANSPORT UDPV4 BLOCKING ALWAYS

Default value for NDDS Transport UDPv4 Property t::send blocking

( p. 1539) to specify blocking sockets.

#deﬁne NDDS TRANSPORT UDPV4 PROPERTY -

DEFAULT

Use this to initialize a NDDS Transport UDPv4 Property t ( p. 1533)

structure.

Functions

NDDS Transport Plugin ∗ NDDS Transport UDPv4 new (const

struct NDDS Transport UDPv4 Property t ∗property in)

Create an instance of a UDPv4 Transport Plugin.

RTI INT32 NDDS Transport UDPv4 string to address cEA

(NDDS Transport Plugin ∗self, NDDS Transport Address t

∗address out, const char ∗address in)

Realization of NDDS Transport String To Address Fcn cEA for IP trans-

ports.

RTI INT32 NDDS Transport UDPv4 get receive interfaces cEA

(NDDS Transport Plugin ∗self, RTI INT32 ∗found more than provided -

for out, RTI INT32 ∗interface reported count out, NDDS Transport -

Interface t interface array inout[ ], RTI INT32 interface array size in)

Realization of NDDS Transport Get Receive Interfaces Fcn cEA for IP

transports.

NDDS Transport Plugin ∗ NDDS Transport UDPv4 create

(NDDS Transport Address t ∗default network address out, const

struct DDS PropertyQosPolicy ∗property in)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.66 UDPv4 Transport 267

Create an instance of a UDPv4 Transport Plugin, using P ropertyQosPolicy.

5.66.1 Detailed Description

Built-in transport plug-in using UDP/IPv4 (NDDS TRANSPORT -

CLASSID UDPv4 (p. 268)).

This transport plugin uses UDPv4 sockets to send and receive messages. It

supports both unicast and multicast communications in a single instance of the

plugin. By default, this plugin will use all interfaces that it ﬁnds enabled and

”UP” at instantiation time to send and receive messages.

The user can conﬁgure an instance of this plugin to only use unicast or only use

multicast, see NDDS Transport UDPv4 Prop e rty t::unicast enabled

(p. 1536) and NDDS Transport UDPv4 Property t::multicast enabled

(p. 1536).

In addition, the user can conﬁgure an instance of this plugin to selectively use

the network interfaces of a node (and restrict a plugin from sending multicast

messages on speciﬁc interfaces) by specifying the ”white” and ”black” lists in the

base property’s ﬁelds (NDDS Transport Property t: :all ow interfaces li st

(p. 1526), NDDS Transport Property t::deny interfaces li st (p. 1526),

NDDS Transport Property t::allow multicast interfaces list (p. 1527),

NDDS Transport Property t::deny multicast interfaces list (p. 1528)).

RTI Connext can implicitly create this plugin and register with the DDS-

DomainParticipant (p. 1139) if this transport is speciﬁed in DDS -

TransportBuiltinQosPolicy (p. 969).

To specify the properties of the builtin UDPv4 transp ort that is implicitly reg-

istered, you can either:

call NDDSTransportSupport::set builtin transport property

(p. 1564) or

specify the predeﬁned property names in DDS PropertyQosPolicy

(p. 834) associated with the DDSDomainParticipant (p. 1139). (see

UDPv4 Transport Property Names in Property QoS Policy of

Domain Participant (p. 268)). Builtin transport plugin properties spec-

iﬁed in DDS PropertyQosPolicy (p. 834) always overwrite the ones

speciﬁed through NDDSTransportSupport::set builtin transport -

property() (p. 1564). The default value is assumed on any unspeciﬁed

prop e rty.

Note that all properties should be set before the transp ort is implicitly cre-

ated and registered by RTI Connext. Any properties set after the builtin

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

268 Module Documentation

transport is registered will be ignored. See Built-in Transport Plu-

gins (p. 136) for details on when a builtin transport is registered. To

explicitly create an instance of this plugin, NDDS Transport UDPv4 -

new() (p. 270) should be called. The instance should be registered with

RTI Connext, see NDDSTransportSupport::register transport (p. 1560).

In some conﬁgurations one may have to disable the builtin UDPv4 trans-

port plugin instance (DDS TransportBuiltinQosPolicy (p. 969), DDS -

TRANSPORTBUILTIN UDPv4 (p. 398)), to avoid port conﬂicts with the

newly created plugin instance.

5.66.2 UDPv4 Transport Property Names in Property

QoS Policy of Domain Par ticipant

The following table lists the predeﬁned property names that can be set in DDS -

PropertyQosPolicy (p. 834) of a DDSDomainParticipant (p. 1139) to con-

ﬁgure the builtin UDPv4 transport plugin.

See also:

NDDSTransportSupport::set builtin transport property()

(p. 1564)

5.66.3 Deﬁne Documentation

5.66.3.1 #deﬁne NDDS TRANSPORT CLASSID UDPv4 (1)

Builtin IPv4 UDP/IP Transport-Plugin class ID.

5.66.3.2 #deﬁne NDDS TRANSPORT UDPV4 ADDRESS BIT -

COUNT (32)

Default value of NDDS

Transport Property t::address bit count

(p. 1524).

5.66.3.3 #deﬁne NDDS TRANSPORT UDPV4 PROPERTIES -

BITMAP DEFAULT (0)

Default value of NDDS Transport Property t::properties bitmap

(p. 1524).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.66 UDPv4 Transport 269

5.66.3.4 #deﬁne NDDS TRANSPORT UDPV4 GATHER SEND -

BUFFER COUNT MAX DEFAULT (16)

Default value of NDDS Transport Property t: :gather send buﬀer -

count max (p. 1525).

This is also the maximum value that can be use d when instantiating the udp

transport.

16 is suﬃcient for RTI Connext, but more may improve discovery and reliable

performance. Porting note: ﬁnd out what the maximum gather buﬀer count is

on your OS!

5.66.3.5 #deﬁne NDDS TRANSPORT UDPV4 SOCKET -

BUFFER SIZE OS DEFAULT (-1)

Used to specify that os default be used to specify socket buﬀer size.

5.66.3.6 #deﬁne NDDS TRANSPORT UDPV4 MESSAGE SIZE -

MAX DEFAULT (9216)

Default value of NDDS Transport Property t::message size max

(p. 1525).

5.66.3.7 #deﬁne NDDS TRANSPORT UDPV4 MULTICAST -

TTL DEFAULT (1)

Default value of NDDS Transport UDPv4 Property t::multicast ttl

(p. 1536).

5.66.3.8 #deﬁne NDDS TRANSPORT UDPV4 BLOCKING -

NEVER

Value for NDDS Transport UDPv4 Property t::send blocking (p. 1539)

to specify non-blocking sockets.

5.66.3.9 #deﬁne NDDS TRANSPORT UDPV4 BLOCKING -

ALWAYS

[default] Value for NDDS Transport UDPv4 Property t::send -

blocking (p. 1539) to specify blocking sockets.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

270 Module Documentation

5.66.3.10 #deﬁne NDDS TRANSPORT UDPV4 BLOCKING -

DEFAULT NDDS TRANSPORT UDPV4 BLOCKING -

ALWAYS

Default value for NDDS

Transport UDPv4 Property t::send blocking

(p. 1539) to specify blocking sockets.

5.66.3.11 #deﬁne NDDS TRANSPORT UDPV4 PROPERTY -

DEFAULT

Value:

{ \

{ NDDS_TRANSPORT_CLASSID_UDPv4, \

NDDS_TRANSPORT_UDPV4_ADDRESS_BIT_COUNT, \

NDDS_TRANSPORT_UDPV4_PROPERTIES_BITMAP_DEFAULT, \

NDDS_TRANSPORT_UDPV4_GATHER_SEND_BUFFER_COUNT_MAX_DEFAULT, \

NDDS_TRANSPORT_UDPV4_MESSAGE_SIZE_MAX_DEFAULT, \

NULL, 0, /* allow_interfaces_list */ \

NULL, 0, /* deny_interfaces_list */ \

NULL, 0, /* allow_multicast_interfaces_list */ \

NULL, 0, /* deny_multicast_interfaces_list */ \

}, \

NDDS_TRANSPORT_UDPV4_MESSAGE_SIZE_MAX_DEFAULT, \

1, /* use unicast */ \

NDDS_TRANSPORT_UDPV4_USE_MULTICAST_DEFAULT, /* use multicast */ \

NDDS_TRANSPORT_UDPV4_MULTICAST_TTL_DEFAULT, \

0, /* multicast loopback enabled */ \

-1, /* (auto-)ignore loopback */ \

1, /* ignore_nonup_interfaces */ \

0, /* do not ignore non-RUNNING */ \

0, /* no_zero_copy */ \

NDDS_TRANSPORT_UDPV4_BLOCKING_DEFAULT, \

0, 0, 0xff /* no mapping to IP_TOS by default */, \

1, /* send_ping */ \

500, /* 500 millisecs is the default polling period*/ \

1, /* reuse multicast rec eive resource */ \

28 /* protocol_overhead_max (UDP(8)+IP(20)) */}

Use this to initialize a NDDS Transport UDPv4 Property t (p. 1533)

structure.

5.66.4 Function Documentation

5.66.4.1 NDDS Transp ort Plugin∗ NDDS Transp ort UDPv4 new

(const struct NDDS Transport UDPv4 Property t ∗

property in)

Create an instance of a UDPv4 Transport Plugin.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.66 UDPv4 Transport 271

An application may create and register multiple instances of this Transport

Plugin with RTI Connext. This may be to partition the network interfaces across

multiple RTI Connext domains. However, note that the underlying transport,

the operating syste m’s IP layer, is still a ”singleton”. For example, if a unicast

transport has already bound to a port, and another unicast transport tries to

bind to the same port, the second attempt will fail.

The transport plugin honors the interface/multicast ”white” and ”black” lists

speciﬁed in the NDDS Transport UDPv4 Prop e rty t::parent (p. 1534):

NDDS Transport Property t::allow interfaces list (p. 1526),

NDDS Transport Property t::deny interfaces list (p. 1526),

NDDS Transport Property t::allow multicast interfaces list

(p. 1527),

NDDS Transport Property t::deny multicast interfaces list

(p. 1528)

The format of a string in these lists is assumed to be in standard IPv4 dot

notation, possibly containing wildcards. For example:

10.10.30.232

10.10.∗.∗

192.168.1.∗

etc. Strings not in the correct format will be ignored.

Parameters:

property in <<in>> ( p. 200) Desired behavior of this transport. May

be NULL for default property.

Returns:

A UDPv4 Transport Plugin instance on success; or NULL on failure.

5.66.4.2 RTI INT32 NDDS Transport UDPv4 string to -

address cEA (NDDS Transport Plugin ∗ self,

NDDS Transport Address t ∗ address out, const char ∗

address in)

Realization of NDDS Transport String To Address Fcn cEA for IP transports.

Converts a host name string to a IPv4 address.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

272 Module Documentation

Parameters:

self NOT USED. May be NULL.

address out <<out>> ( p. 200) The corresponding numerical value in

IPv6 format.

address in <<in>> ( p. 200 ) The name of the IPv4 address. It can be a

dot notation name or a host name. If NULL, then the IP address of

the localhost will be returned.

See also:

NDDS Transport String To Address Fcn cEA for complete documenta-

tion.

5.66.4.3 RTI INT32 NDDS Transport UDPv4 get receive -

interfaces cEA (NDDS Transp ort Plugin ∗ self,

RTI INT32 ∗ found more than provided for out,

RTI INT32 ∗ interface reported count out,

NDDS Transport Interface t interface array inout[ ],

RTI INT32 interface array size in)

Realization of NDDS Transport Get Receive Interfaces Fcn cEA for IP trans-

ports.

Retrieves a list of available IPv4 network interfaces. The addresses returned

from IPv4 plugin will be of the pattern 0.0.0.0.0.0.0.0.0.0.0.0.x.x.x.x.

See also:

NDDS Transport Get Receive Interfaces Fcn cEA for complete documen-

tation.

5.66.4.4 NDDS Transp ort Plugin∗ NDDS Transport -

UDPv4 create (NDDS Transport Address t

∗ default network address out, const struct

DDS PropertyQosPoli cy ∗ property in)

Create an instance of a UDPv4 Transport Plugin, using PropertyQosPolicy.

An application may create and register multiple instances of this Transport

Plugin with RTI Connext. This may be to partition the network interfaces across

multiple RTI Connext domains. However, note that the underlying transport,

the operating syste m’s IP layer, is still a ”singleton”. For example, if a unicast

transport has already bound to a port, and another unicast transport tries to

bind to the same port, the second attempt will fail.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.66 UDPv4 Transport 273

The transport plugin honors the interface/multicast ”white” and ”black” lists

speciﬁed in the NDDS Transport UDPv4 Prop e rty t::parent (p. 1534):

NDDS Transport Property t::allow interfaces list (p. 1526),

NDDS Transport Property t::deny interfaces list (p. 1526),

NDDS Transport Property t::allow multicast interfaces list

(p. 1527),

NDDS Transport Property t::deny multicast interfaces list

(p. 1528)

The format of a string in these lists is assumed to be in standard IPv4 dot

notation, possibly containing wildcards. For example:

10.10.30.232

10.10.∗.∗

192.168.1.∗

etc. Strings not in the correct format will be ignored.

Parameters:

default network address out <<out>> ( p. 200) Network address to

be used when registering the transport.

property in <<in>> ( p. 200) Desired behavior of this transport,

through the property ﬁeld in DDS DomainParticipantQos

(p. 588).

Returns:

A UDPv4 Transport Plugin instance on success; or NULL on failure.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

274 Module Documentation

Property Name Description

dds.transp ort.UDPv4.builtin.parent.address -

bit count

See NDDS Transport -

Property t::address bit count

(p. 1524)

dds.transp ort.UDPv4.builtin.parent.properties -

bitmap

See NDDS Transport -

Property t::properties bitmap

(p. 1524)

dds.transp ort.UDPv4.builtin.parent.gather -

send buﬀer count max

See NDDS Transport -

Property t::gather send -

buﬀer count max

(p. 1525)

dds.transp ort.UDPv4.builtin.parent.message -

size max

See NDDS Transport -

Property t::message size max

(p. 1525)

dds.transp ort.UDPv4.builtin.parent.allow -

inte rfaces

See NDDS Transport -

Property t::allow int erfaces list

(p. 1526) and

NDDS Transport Property -

t::allow interfaces li st length

(p. 1526).

Interfaces should be speciﬁed as

comma-separated strings, with each

comma delimiting an interface. For

example, 127.0.0.1,eth0

dds.transp ort.UDPv4.builtin.parent.deny -

inte rfaces

See NDDS Transport -

Property t::deny int erfaces list

(p. 1526) and

NDDS Transport Property -

t::deny interfaces li st length

(p. 1527).

Interfaces should be speciﬁed as

comma-separated strings, with each

comma delimiting an interface. For

example: 127.0.0.1,eth0

dds.transp ort.UDPv4.builtin.parent.allow -

multicast interfaces

See

NDDS Transport Property -

t::allow multicast interfaces list

(p. 1527) and NDDS Transport -

Property t::allow mul ticast -

interfaces list length

(p. 1528).

Interfaces should be speciﬁed as

comma-separated strings, with each

comma delimiting an interface. For

example: 127.0.0.1,eth0

dds.transp ort.UDPv4.builtin.parent.deny -

multicast interfaces

See

NDDS Transport Property -

t::deny multicast interfaces list

(p. 1528) and NDDS Transport -

Property t::deny mul ticast -

interfaces list length (p. 1528).

Interfaces should be speciﬁed as

comma-separated strings, with each

comma delimiting an interface. For

example: 127.0.0.1,eth0

dds.transp ort.UDPv4.builtin.send -

socket buﬀer size

See NDDS Transport UDPv4 -

Property t::send socket buﬀer -

size

(p. 1535)

dds.transp ort.UDPv4.builtin.recv -

socket buﬀer size

See NDDS Transport UDPv4 -

Property t::recv socket buﬀer -

size

(p. 1535)

dds.transp ort.UDPv4.builtin.unicast -

enabled

See NDDS Transport UDPv4 -

Property t::unicast enabled

(p. 1536)

dds.transp ort.UDPv4.builtin.multicast -

enabled

See NDDS Transport UDPv4 -

Property t::multicast enabled

(p. 1536)

dds.transp ort.UDPv4.builtin.multicast -

ttl

See NDDS Transport UDPv4 -

Property t::multicast ttl

(p. 1536)

dds.transp ort.UDPv4.builtin.multicast -

loopback disabled

See NDDS Transport UDPv4 -

Property t::multicast -

loopback disabled

(p. 1536)

dds.transp ort.UDPv4.builtin.ignore -

loopback interface

See NDDS Transport UDPv4 -

Property t::ignore loopback -

interface

(p. 1537)

dds.transp ort.UDPv4.builtin.ignore -

nonrunning interfaces

See NDDS Transport UDPv4 -

Property t::ignore -

nonrunning interfaces

(p. 1538)

dds.transp ort.UDPv4.builtin.no -

zero copy

See NDDS Transport UDPv4 -

Property t::no zero copy

(p. 1538)

dds.transp ort.UDPv4.builtin.send -

blocking

See NDDS Transport UDPv4 -

Property t::send blocking

(p. 1539)

dds.transp ort.UDPv4.builtin.transport -

priority mask

See NDDS Transport UDPv4 -

Property t::transport priority -

mask

(p. 1539)

dds.transp ort.UDPv4.builtin.transport -

priority mapping low

See NDDS Transport UDPv4 -

Property t::transport priority -

mapping low

(p. 1540)

dds.transp ort.UDPv4.builtin.transport -

priority mapping high

See NDDS Transport UDPv4 -

Property t::transport priority -

mapping high

(p. 1540)

dds.transp ort.UDPv4.builtin.interface -

poll period

See NDDS Transport UDPv4 -

Property t::interface poll -

period

(p. 1540)

dds.transp ort.UDPv4.builtin.reuse -

multicast receive resource

See NDDS Transport UDPv4 -

Property t::reuse multicast -

receive resource

(p. 1540)

dds.transp ort.UDPv4.builtin.protocol -

overhead max

See NDDS Transport UDPv4 -

Property t::protocol overhead -

max

(p. 1541)

Table 5.9: Property Names for UDPv4 Transport Plugin

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.67 UDPv6 Transport 275

5.67 UDPv6 Transport

Built-in transport plug-in using UDP/IPv6 (NDDS TRANSPORT -

CLASSID UDPv6 (p. 278)).

Classes

struct NDDS Transport UDPv6 Property t

Conﬁgurable IPv6/UDP Transport-Pl ugin properties.

Deﬁnes

#deﬁne NDDS TRANSPORT CLASSID UDPv6 (5)

Builtin IPv6 UDP/IP Transport-Plugin class ID.

#deﬁne NDDS TRANSPORT UDPV6 ADDRESS BIT -

COUNT (128)

Default value of NDDS Transport Property t::address bit count

( p. 1524).

#deﬁne NDDS TRANSPORT UDPV6 PROPERTIES -

BITMAP DEFAULT (0)

Default value of NDDS Transport Property t::properties bitmap

( p. 1524).

#deﬁne NDDS TRANSPORT UDPV6 GATHER SEND -

BUFFER COUNT MAX DEFAULT (16)

Default value of NDDS Transport Property t::gather send buﬀer -

count max ( p. 1525).

#deﬁne NDDS TRANSPORT UDPV6 SOCKET BUFFER -

SIZE OS DEFAULT (-1)

Used to specify that os default be used to specify socket buﬀer size.

#deﬁne NDDS TRANSPORT UDPV6 MESSAGE SIZE -

MAX DEFAULT (9216)

Default value of NDDS Transport Prope rty t::message size max

( p. 1525).

#deﬁne NDDS TRANSPORT UDPV6 MULTICAST TTL -

DEFAULT (1)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

276 Module Documentation

Default value of NDDS Transport UDPv6 Property t::multicast ttl

( p. 1545).

#deﬁne NDDS TRANSPORT UDPV6 BLOCKING NEVER

Value for NDDS Transport UDPv6 Property t::send blocking

( p. 1547) to specify non-blocking sockets.

#deﬁne NDDS TRANSPORT UDPV6 BLOCKING ALWAYS

[default] Value for NDDS Transport UDPv6 Property t::send -

blocking ( p. 1547) to specify blocking sockets.

#deﬁne NDDS TRANSPORT UDPV6 PROPERTY -

DEFAULT

Use this to initialize a NDDS Transport UDPv6 Property t ( p. 1542)

structure.

Functions

NDDS Transport Plugin ∗ NDDS Transport UDPv6 new (const

struct NDDS Transport UDPv6 Property t ∗property in)

Create an instance of a UDPv6 Transport Plugin.

RTI INT32 NDDS Transport UDPv6 string to address cEA

(NDDS Transport Plugin ∗self, NDDS Transport Address t

∗address out, const char ∗address in)

Realization of NDDS Transport String To Address Fcn cEA for IP trans-

ports.

RTI INT32 NDDS Transport UDPv6 get receive interfaces cEA

(NDDS Transport Plugin ∗self, RTI INT32 ∗found more than provided -

for out, RTI INT32 ∗interface reported count out, NDDS Transport -

Interface t interface array inout[ ], RTI INT32 interface array size in)

Realization of NDDS Transport Get Receive Interfaces Fcn cEA for IP

transports.

NDDS Transport Plugin ∗ NDDS Transport UDPv6 create

(NDDS Transport Address t ∗default network address out, const

struct DDS PropertyQosPolicy ∗property in)

Create an instance of a UDPv6 Transport Plugin, using P ropertyQosPolicy.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.67 UDPv6 Transport 277

5.67.1 Detailed Description

Built-in transport plug-in using UDP/IPv6 (NDDS TRANSPORT -

CLASSID UDPv6 (p. 278)).

This transport plugin uses UDPv6 sockets to send and receive messages. It

supports both unicast and multicast communications in a single instance of the

plugin. By default, this plugin will use all interfaces that it ﬁnds enabled and

”UP” at instantiation time to send and receive messages.

The user can conﬁgure an instance of this plugin to only use unicast or only use

multicast, see NDDS Transport UDPv6 Prop e rty t::unicast enabled

(p. 1544) and NDDS Transport UDPv6 Property t::multicast enabled

(p. 1545).

In addition, the user can conﬁgure an instance of this plugin to selectively use

the network interfaces of a node (and restrict a plugin from sending multicast

messages on speciﬁc interfaces) by specifying the ”white” and ”black” lists in the

base property’s ﬁelds (NDDS Transport Property t: :all ow interfaces li st

(p. 1526), NDDS Transport Property t::deny interfaces li st (p. 1526),

NDDS Transport Property t::allow multicast interfaces list (p. 1527),

NDDS Transport Property t::deny multicast interfaces list (p. 1528)).

RTI Connext can implicitly create this plugin and register it with the DDS-

DomainParticipant (p. 1139) if this transport is speciﬁed in the DDS -

TransportBuiltinQosPolicy (p. 969).

To specify the properties of the builtin UDPv6 transp ort that is implicitly reg-

istered, you can either:

call NDDSTransportSupport::set builtin transport property

(p. 1564) or

specify the predeﬁned property names in DDS PropertyQosPolicy

(p. 834) associated with the DDSDomainParticipant (p. 1139). (see

UDPv6 Transport Property Names in Property QoS Policy of

Domain Participant (p. 278)). Builtin transport plugin properties spec-

iﬁed in DDS PropertyQosPolicy (p. 834) always overwrite the ones

speciﬁed through NDDSTransportSupport::set builtin transport -

property() (p. 1564). The default value is assumed on any unspeciﬁed

prop e rty.

Note that all properties should be set before the transp ort is implicitly cre-

ated and registered by RTI Connext. Any properties that are set after the

builtin transport is registered will be ignored. See Built-in Transp ort Plug-

ins (p. 136) for details on when a builtin transport is registered.

To explicitly create an instance of this plugin, NDDS Transport UDPv6 -

new() (p. 280) should be called. The instance should be registered with

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

278 Module Documentation

RTI Connext, see NDDSTransportSupport::register transport (p. 1560).

In some conﬁgurations, you may have to disable the builtin UDPv6 trans-

port plugin instance (DDS TransportBuiltinQosPolicy (p. 969), DDS -

TRANSPORTBUILTIN UDPv6 (p. 398)), to avoid port conﬂicts with the

newly created plugin instance.

5.67.2 UDPv6 Transport Property Names in Property

QoS Policy of Domain Par ticipant

The following table lists the predeﬁned property names that can be set in DDS -

PropertyQosPolicy (p. 834) of a DDSDomainParticipant (p. 1139) to con-

ﬁgure the builtin UDPv6 transport plugin.

See also:

NDDSTransportSupport::set builtin transport property()

(p. 1564)

5.67.3 Deﬁne Documentation

5.67.3.1 #deﬁne NDDS TRANSPORT CLASSID UDPv6 (5)

Builtin IPv6 UDP/IP Transport-Plugin class ID.

5.67.3.2 #deﬁne NDDS TRANSPORT UDPV6 ADDRESS BIT -

COUNT (128)

Default value of NDDS Transport Property t::address bit count

(p. 1524).

5.67.3.3 #deﬁne NDDS TRANSPORT UDPV6 PROPERTIES -

BITMAP DEFAULT (0)

Default value of NDDS Transport Property t::properties bitmap

(p. 1524).

5.67.3.4 #deﬁne NDDS TRANSPORT UDPV6 GATHER SEND -

BUFFER COUNT MAX DEFAULT (16)

Default value of NDDS Transport Property t: :gather send buﬀer -

count max (p. 1525).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.67 UDPv6 Transport 279

This is also the maximum value that can be use d when instantiating the udp

transport.

16 is suﬃcient for NDDS, but more may improve discovery and reliable perfor-

mance. Porting note: ﬁnd out what the maximum gather buﬀer count is on

your OS!

5.67.3.5 #deﬁne NDDS TRANSPORT UDPV6 SOCKET -

BUFFER SIZE OS DEFAULT (-1)

Used to specify that os default be used to specify socket buﬀer size.

5.67.3.6 #deﬁne NDDS TRANSPORT UDPV6 MESSAGE SIZE -

MAX DEFAULT (9216)

Default value of NDDS Transport Property t::message size max

(p. 1525).

5.67.3.7 #deﬁne NDDS TRANSPORT UDPV6 MULTICAST -

TTL DEFAULT (1)

Default value of NDDS Transport UDPv6 Property t::multicast ttl

(p. 1545).

5.67.3.8 #deﬁne NDDS TRANSPORT UDPV6 BLOCKING -

NEVER

Value for NDDS Transport UDPv6 Property t::send blocking (p. 1547)

to specify non-blocking sockets.

5.67.3.9 #deﬁne NDDS TRANSPORT UDPV6 BLOCKING -

ALWAYS

[default] Value for NDDS Transport UDPv6 Property t::send -

blocking (p. 1547) to specify blocking sockets.

5.67.3.10 #deﬁne NDDS TRANSPORT UDPV6 PROPERTY -

DEFAULT

Value:

{ \

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

280 Module Documentation

{ NDDS_TRANSPORT_CLASSID_UDPv6, \

NDDS_TRANSPORT_UDPV6_ADDRESS_BIT_COUNT, \

NDDS_TRANSPORT_UDPV6_PROPERTIES_BITMAP_DEFAULT, \

NDDS_TRANSPORT_UDPV6_GATHER_SEND_BUFFER_COUNT_MAX_DEFAULT, \

NDDS_TRANSPORT_UDPV6_MESSAGE_SIZE_MAX_DEFAULT, \

NULL, 0, /* allow_interfaces_list */ \

NULL, 0, /* deny_interfaces_list */ \

NULL, 0, /* allow_multicast_interfaces_list */ \

NULL, 0, /* deny_multicast_interfaces_list */ \

}, \

NDDS_TRANSPORT_UDPV6_MESSAGE_SIZE_MAX_DEFAULT, \

1, /* use unicast */ \

NDDS_TRANSPORT_UDPV6_USE_MULTICAST_DEFAULT, /* use multicast */ \

NDDS_TRANSPORT_UDPV6_MULTICAST_TTL_DEFAULT, \

0, /* multicast loopback enabled */ \

-1, /* (auto-)ignore loopback */ \

0, /* do not ignore non-RUNNING */ \

0, /* no_zero_copy */ \

NDDS_TRANSPORT_UDPV6_BLOCKING_DEFAULT, \

0, /* enable_ v4m appe d */ \

0, 0, 0xff /* no mapping to IPV6_TCLASS by default */ }

Use this to initialize a NDDS Transport UDPv6 Property t (p. 1542)

structure.

5.67.4 Function Documentation

5.67.4.1 NDDS Transp ort Plugin∗ NDDS Transp ort UDPv6 new

(const struct NDDS Transport UDPv6 Property t ∗

property in)

Create an instance of a UDPv6 Transport Plugin.

An application may create and register multiple instances of this Transport

Plugin with RTI Connext. This may be to partition the network interfaces across

multiple RTI Connext domains. However, note that the underlying transport,

the operating syste m’s IP layer, is still a ”singleton”. For example, if a unicast

transport has already bound to a port, and another unicast transport tries to

bind to the same port, the second attempt will fail.

The transport plugin honors the interface/multicast ”white” and ”black” lists

speciﬁed in the NDDS Transport UDPv6 Prop e rty t::parent (p. 1543):

NDDS Transport Property t::allow interfaces list (p. 1526),

NDDS Transport Property t::deny interfaces list (p. 1526),

NDDS Transport Property t::allow multicast interfaces list

(p. 1527),

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.67 UDPv6 Transport 281

NDDS Transport Property t::deny multicast interfaces list

(p. 1528)

The format of a string in these lists is assumed to be in standard IPv6 dot

notation, possibly containing wildcards. For example:

10.10.30.232

10.10.∗.∗

192.168.1.∗

etc. Strings not in the correct format will be ignored.

Parameters:

property in <<in>> ( p. 200) Desired behavior of this transport. May

be NULL for default property.

Returns:

A UDPv6 Transport Plugin instance on success; or NULL on failure.

5.67.4.2 RTI INT32 NDDS Transport UDPv6 string to -

address cEA (NDDS Transport Plugin ∗ self,

NDDS Transport Address t ∗ address out, const char ∗

address in)

Realization of NDDS Transport String To Address Fcn cEA for IP transports.

Converts a host name string to a IPv6 address.

Parameters:

self NOT USED. May be NULL.

address out <<out>> ( p. 200) The corresponding numerical value in

IPv6 format.

address in <<in>> ( p. 200 ) The name of the IPv6 address. It can be a

dot notation name or a host name. If NULL, then the IP address of

the localhost will be returned.

See also:

NDDS Transport String To Address Fcn cEA for complete documenta-

tion.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

282 Module Documentation

5.67.4.3 RTI INT32 NDDS Transport UDPv6 get receive -

interfaces cEA (NDDS Transp ort Plugin ∗ self,

RTI INT32 ∗ found more than provided for out,

RTI INT32 ∗ interface reported count out,

NDDS Transport Interface t interface array inout[ ],

RTI INT32 interface array size in)

Realization of NDDS Transport Get Receive Interfaces Fcn cEA for IP trans-

ports.

Retrieves a list of available IPv6 network interfaces. The addresses returned

from IPv6 plugin will be full 128-bit addresses.

See also:

NDDS Transport Get Receive Interfaces Fcn cEA for complete documen-

tation.

5.67.4.4 NDDS Transp ort Plugin∗ NDDS Transport -

UDPv6 create (NDDS Transport Address t

∗ default network address out, const struct

DDS PropertyQosPoli cy ∗ property in)

Create an instance of a UDPv6 Transport Plugin, using PropertyQosPolicy.

An application may create and register multiple instances of this Transport

Plugin with RTI Connext. This may be to partition the network interfaces across

multiple RTI Connext domains. However, note that the underlying transport,

the operating syste m’s IP layer, is still a ”singleton”. For example, if a unicast

transport has already bound to a port, and another unicast transport tries to

bind to the same port, the second attempt will fail.

The transport plugin honors the interface/multicast ”white” and ”black” lists

speciﬁed in the NDDS Transport UDPv6 Prop e rty t::parent (p. 1543):

NDDS Transport Property t::allow interfaces list (p. 1526),

NDDS Transport Property t::deny interfaces list (p. 1526),

NDDS Transport Property t::allow multicast interfaces list

(p. 1527),

NDDS Transport Property t::deny multicast interfaces list

(p. 1528)

The format of a string in these lists is assumed to be in standard IPv6 dot

notation, possibly containing wildcards. For example:

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.67 UDPv6 Transport 283

∗:∗:∗:∗:∗:∗:∗:∗

FE80:aBc::202:∗:∗

∗:aBC::∗2:∗:2∗

etc. Strings not in the correct format will be ignored.

Parameters:

default network address out <<out>> ( p. 200) Network address to

be used when registering the transport.

property in <<in>> ( p. 200) Desired behavior of this transport,

through the property ﬁeld in DDS DomainParticipantQos

(p. 588).

Returns:

A UDPv6 Transport Plugin instance on success; or NULL on failure.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

284 Module Documentation

Property Name Description

dds.transp ort.UDPv6.builtin.parent.address -

bit count

See NDDS Transport -

Property t::address bit count

(p. 1524)

dds.transp ort.UDPv6.builtin.parent.properties -

bitmap

See NDDS Transport -

Property t::properties bitmap

(p. 1524)

dds.transp ort.UDPv6.builtin.parent.gather -

send buﬀer count max

See NDDS Transport -

Property t::gather send -

buﬀer count max

(p. 1525)

dds.transp ort.UDPv6.builtin.parent.message -

size max

See NDDS Transport -

Property t::message size max

(p. 1525)

dds.transp ort.UDPv6.builtin.parent.allow -

inte rfaces

See NDDS Transport -

Property t::allow int erfaces list

(p. 1526) and

NDDS Transport Property -

t::allow interfaces li st length

(p. 1526).

Interfaces should be speciﬁed as

comma-separated strings, with each

comma delimiting an interface. For

example: 127.0.0.1,eth0

dds.transp ort.UDPv6.builtin.parent.deny -

inte rfaces

See NDDS Transport -

Property t::deny int erfaces list

(p. 1526) and

NDDS Transport Property -

t::deny interfaces li st length

(p. 1527).

Interfaces should be speciﬁed as

comma-separated strings, with each

comma delimiting an interface. For

example: 127.0.0.1,eth0

dds.transp ort.UDPv6.builtin.parent.allow -

multicast interfaces

See

NDDS Transport Property -

t::allow multicast interfaces list

(p. 1527) and NDDS Transport -

Property t::allow mul ticast -

interfaces list length

(p. 1528).

Interfaces should be speciﬁed as

comma-separated strings, with each

comma delimiting an interface. For

example: 127.0.0.1,eth0

dds.transp ort.UDPv6.builtin.parent.deny -

multicast interfaces

See

NDDS Transport Property -

t::deny multicast interfaces list

(p. 1528) and NDDS Transport -

Property t::deny mul ticast -

interfaces list length (p. 1528).

Interfaces should be speciﬁed as

comma-separated strings, with each

comma delimiting an interface. For

example: 127.0.0.1,eth0

dds.transp ort.UDPv6.builtin.send -

socket buﬀer size

See NDDS Transport UDPv6 -

Property t::send socket buﬀer -

size

(p. 1543)

dds.transp ort.UDPv6.builtin.recv -

socket buﬀer size

See NDDS Transport UDPv6 -

Property t::recv socket buﬀer -

size

(p. 1544)

dds.transp ort.UDPv6.builtin.unicast -

enabled

See NDDS Transport UDPv6 -

Property t::unicast enabled

(p. 1544)

dds.transp ort.UDPv6.builtin.multicast -

enabled

See NDDS Transport UDPv6 -

Property t::multicast enabled

(p. 1545)

dds.transp ort.UDPv6.builtin.multicast -

ttl

See NDDS Transport UDPv6 -

Property t::multicast ttl

(p. 1545)

dds.transp ort.UDPv6.builtin.multicast -

loopback disabled

See NDDS Transport UDPv6 -

Property t::multicast -

loopback disabled

(p. 1545)

dds.transp ort.UDPv6.builtin.ignore -

loopback interface

See NDDS Transport UDPv6 -

Property t::ignore loopback -

interface

(p. 1545)

dds.transp ort.UDPv6.builtin.ignore -

nonrunning interfaces

See NDDS Transport UDPv6 -

Property t::ignore -

nonrunning interfaces

(p. 1546)

dds.transp ort.UDPv6.builtin.no -

zero copy

See NDDS Transport UDPv6 -

Property t::no zero copy

(p. 1547)

dds.transp ort.UDPv6.builtin.send -

blocking

See NDDS Transport UDPv6 -

Property t::send blocking

(p. 1547)

dds.transp ort.UDPv6.builtin.enable -

v4mapped

See NDDS Transport UDPv6 -

Property t::enable v4mapped

(p. 1547)

dds.transp ort.UDPv6.builtin.transport -

priority mask

See NDDS Transport UDPv6 -

Property t::transport priority -

mask

(p. 1548)

dds.transp ort.UDPv6.builtin.transport -

priority mapping low

See NDDS Transport UDPv6 -

Property t::transport priority -

mapping low

(p. 1548)

dds.transp ort.UDPv6.builtin.transport -

priority mapping high

See NDDS Transport UDPv6 -

Property t::transport priority -

mapping high

(p. 1548)

Table 5.10: Property Names for UDPv6 Transport Plugin

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.68 Participant Built-in Topics 285

5.68 Participant Built-in Topics

Builtin topic for accessing information about the DomainParticipants discovered

by RTI Connext.

Classes

class DDSParticipantBuiltinTopicDataTypeSupport

Instantiates TypeSupport < DDS ParticipantBuiltinTopicData ( p. 816)

> .

class DDSParticipantBuiltinTopicDataDataReader

Instantiates DataReader < DDS ParticipantBuiltinTopicData ( p. 816)

> .

struct DDS ParticipantBuiltinTopicData

Entry created when a DomainParticipant object is discovered.

struct DDS ParticipantBuiltinTopicDataSeq

Instantiates FooSeq (p. 1494) < DDS ParticipantBuiltinTopicData

( p. 816) > .

Variables

const char ∗ DDS PARTICIPANT TOPIC NAME

Participant topic name.

5.68.1 Detailed Description

Builtin topic for accessing information about the DomainParticipants discovered

by RTI Connext.

5.68.2 Variable Documentation

5.68.2.1 const char∗ DDS PARTICIPANT TOPIC NAME

Participant topic name.

Topic name of DDSParticipantBuiltinTopicDataDataReader (p. 1341)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

286 Module Documentation

See also:

DDS ParticipantBuiltinTopicData (p. 816)

DDSParticipantBuiltinTopicDataDataReader (p. 1341)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.69 Topic Built-in Topics 287

5.69 Topic Built-in Topics

Builtin topic for accessing information about the Topics discovered by RTI Con-

next.

Classes

class DDSTopicBuiltinTopicDataTypeSupport

Instantiates TypeSupport < DDS TopicBuiltinTopicData ( p. 958) > .

class DDSTopicBuiltinTopicDataDataReader

Instantiates DataReader < DDS TopicBuiltinTopicData ( p. 958) > .

struct DDS TopicBuiltinTopicData

Entry created when a Topic object discovered.

struct DDS TopicBuiltinTopicDataSeq

Instantiates FooSeq (p. 1494) < DDS TopicBuiltinTopicData ( p. 958)

> .

Variables

const char ∗ DDS TOPIC TOPIC NAME

Topic topic name.

5.69.1 Detailed Description

Builtin topic for accessing information about the Topics discovered by RTI Con-

next.

5.69.2 Variable Documentation

5.69.2.1 const char∗ DDS TOPIC TOPIC NAME

Topic topic name.

Topic name of DDSTopicBuiltinTopicDataDataReader (p. 1425)

See also:

DDS TopicBuilti nTopicData (p. 958)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

288 Module Documentation

DDSTopicBuiltinTopicDataDataReader (p. 1425)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.70 Publication Built-in Topics 289

5.70 Publication Built-in Topics

Builtin topic for accessing information about the Publications discovered by RTI

Connext.

Classes

class DDSPublicationBuiltinTopicDataTypeSupport

Instantiates TypeSupport < DDS PublicationBuiltinTopicData ( p. 839)

> .

class DDSPublicationBuiltinTopicDataDataReader

Instantiates DataReader < DDS PublicationBuiltinTopicData ( p. 839)

> .

struct DDS PublicationBuiltinTopicData

Entry created when a DDSDataWriter ( p. 1113) is discovered in associa-

tion with its Publisher.

struct DDS PublicationBuiltinTopicDataSeq

Instantiates FooSeq (p. 1494) < DDS PublicationBuiltinTopicData

( p. 839) > .

Variables

const char ∗ DDS PUBLICATION TOPIC NAME

Publication topic name.

5.70.1 Detailed Description

Builtin topic for accessing information about the Publications discovered by RTI

Connext.

5.70.2 Variable Documentation

5.70.2.1 const char∗ DDS PUBLICATION TOPIC NAME

Publication topic name.

Topic name of DDSPublicationBuiltinTopicDataDataReader (p. 1344)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

290 Module Documentation

See also:

DDS PublicationBuiltinTopicData (p. 839)

DDSPublicationBuiltinTopicDataDataReader (p. 1344)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.71 Subscription Built-in Topics 291

5.71 Subscription Built-in Topics

Builtin topic for accessing information about the Subscriptions discovered by

RTI Connext.

Classes

class DDSSubscriptionBuiltinTopicDataTypeSupport

Instantiates TypeSupport < DDS SubscriptionBuiltinTopicData

( p. 936) > .

class DDSSubscriptionBuiltinTopicDataDataReader

Instantiates DataReader < DDS SubscriptionBuiltinTopicData ( p. 936)

> .

struct DDS SubscriptionBuiltinTopicData

Entry created when a DDSDataReader ( p. 1087) is discovered in associa-

tion with its Subscriber.

struct DDS SubscriptionBuiltinTopicDataSeq

Instantiates FooSeq (p. 1494) < DDS SubscriptionBuiltinTopicData

( p. 936) > .

Variables

const char ∗ DDS SUBSCRIPTION TOPIC NAME

Subscription topic name.

5.71.1 Detailed Description

Builtin topic for accessing information about the Subscriptions discovered by

RTI Connext.

5.71.2 Variable Documentation

5.71.2.1 const char∗ DDS SUBSCRIPTION TOPIC NAME

Subscription topic name.

Topic name of DDSSubscriptionBuiltinTopicDataDataReader (p. 1417)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

292 Module Documentation

See also:

DDS SubscriptionBuiltinTopicData (p. 936)

DDSSubscriptionBuiltinTopicDataDataReader (p. 1417)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.72 String Built-in Type 293

5.72 String Built-in Type

Built-in type consisting of a single character string.

Classes

class DDSStringTypeSupport

<<inter face>> (p. 199) String type support.

class DDSStringDataReader

<<inter face>> (p. 199) Instantiates DataReader < char∗ >.

class DDSStringDataWriter

<<inter face>> (p. 199) Instantiates DataWriter < char∗ >.

5.72.1 Detailed Description

Built-in type consisting of a single character string.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

294 Module Documentation

5.73 KeyedString Built-in Type

Built-in type consisting of a string payload and a second string that is the key.

Classes

class DDSKeyedStringTypeSupport

<<inter face>> (p. 199) Keyed string type support.

class DDSKeyedStringDataReader

<<inter face>> (p. 199) Instantiates DataReader < DDS KeyedString

( p. 768) >.

class DDSKeyedStringDataWriter

<<inter face>> (p. 199) Instantiates DataWriter < DDS KeyedString

( p. 768) >.

struct DDS KeyedString

Keyed string built-in type.

struct DDS KeyedStringSeq

Instantiates FooSeq (p. 1494) < DDS KeyedString ( p. 768) > .

5.73.1 Detailed Description

Built-in type consisting of a string payload and a second string that is the key.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.74 Octets Built-in Type 295

5.74 Octets Built-in Type

Built-in type consisting of a variable-length array of opaque bytes.

Classes

class DDSOctetsTypeSupport

<<inter face>> (p. 199) DDS Octets ( p. 799) type support.

class DDSOctetsDataReader

<<inter face>> (p. 199) Instantiates DataReader < DDS Octets ( p. 799)

class DDSOctetsDataWriter

<<inter face>> (p. 199) Instantiates DataWriter < DDS Octets ( p. 799)

struct DDS Octets

Built-in type consisting of a v ariable-le ngth array of opaque bytes.

struct DDS OctetsSeq

Instantiates FooSeq (p. 1494) < DDS Octets ( p. 799) > .

5.74.1 Detailed Description

Built-in type consisting of a variable-length array of opaque bytes.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

296 Module Documentation

5.75 KeyedOctets Built-in Type

Built-in type consisting of a variable-length array of opaque bytes and a string

that is the key.

Classes

class DDSKeyedOctetsTypeSupport

<<inter face>> (p. 199) DDS KeyedOctets ( p. 765) type support.

class DDSKeyedOctetsDataReader

<<inter face>> (p. 199) Instantiates DataReader < DDS KeyedOctets

( p. 765) >.

class DDSKeyedOctetsDataWriter

<<inter face>> (p. 199) Instantiates DataWriter < DDS KeyedOctets

( p. 765) >.

struct DDS KeyedOctets

Built-in type consisting of a variable-length array of opaque bytes and a string

that is the key.

struct DDS KeyedOctetsSeq

Instantiates FooSeq (p. 1494) < DDS KeyedOctets ( p. 765) >.

5.75.1 Detailed Description

Built-in type consisting of a variable-length array of opaque bytes and a string

that is the key.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.76 DDS-Speciﬁc Primitive Types 297

5.76 DDS-Speciﬁc Primitive Types

Basic DDS value types for use in user data types.

Deﬁnes

#deﬁne DDS BOOLEAN TRUE

Deﬁnes ”true” value of DDS Boolean ( p. 301) data type.

#deﬁne DDS BOOLEAN FALSE

Deﬁnes ”false” value of DDS Boolean ( p. 301) data type.

Typedefs

typedef RTICdrChar DDS Char

Deﬁnes a character data type, equivalent to IDL/CDR char.

typedef RTICdrWchar DDS Wchar

Deﬁnes a wide character data type, equivalent to IDL/CDR wchar.

typedef RTICdrOctet DDS Octet

Deﬁnes an opaque byte data type, equivalent to IDL/CDR octet.

typedef RTICdrShort DDS Short

Deﬁnes a short integer data type, equivalent to IDL/CDR short.

typedef RTICdrUnsignedShort DDS UnsignedShort

Deﬁnes an unsigned short integer data type, equivalent to IDL/CDR

unsigned short.

typedef RTICdrLong DDS Long

Deﬁnes a long integer data type, equivalent to IDL/CDR long.

typedef RTICdrUnsignedLong DDS UnsignedLong

Deﬁnes an unsigned long integer data type, equivalent to IDL/CDR unsigned

long.

typedef RTICdrLongLong DDS LongLong

Deﬁnes an extra-long integer data type, equivalent to IDL/CDR long long.

typedef RTICdrUnsignedLongLong DDS UnsignedLongLong

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

298 Module Documentation

Deﬁnes an unsigned extra-long data type, equivalent to IDL/CDR unsigned

long long.

typedef RTICdrFloat DDS Float

Deﬁnes a single-precision ﬂoating-point data type, equivalent to IDL/CDR

float.

typedef RTICdrDouble DDS Double

Deﬁnes a double-precision ﬂoating-point data type, equivalent to IDL/CDR

double.

typedef RTICdrLongDouble DDS LongDouble

Deﬁnes an extra-precision ﬂoating-point data type, equivalent to IDL/CDR

long double.

typedef RTICdrBoolean DDS Boolean

Deﬁnes a Boolean data type, equivalent to IDL/CDR boolean.

typedef RTICdrEnum DDS Enum

Deﬁnes an enumerated data type.

5.76.1 Detailed Description

Basic DDS value types for use in user data types.

As part of the ﬁnalization of the DDS standard, a number of DDS-speciﬁc

primitive types will be introduced. By using these types, you will ensure that

your data is serialized consistently across platforms even if the C/C++ built-in

types have diﬀerent sizes on those platforms.

In this version of RTI Connext, the DDS primitive types are deﬁned using the

OMG’s Common Data Representation (CDR) standard. In a future version of

RTI Connext, you will be given the choice of whether to use these CDR-based

types or C/C++ built-in types through a ﬂag provided to the rtiddsgen tool.

Typedef’s that begin with RTICdr are deﬁned in

<NDDSHOME>/include/ndds/cdr/cdr

type.h, which uses types that are

further deﬁned in <NDDSHOME>/include/ndds/osapi/osapi type.h.

5.76.2 Deﬁne Documentation

5.76.2.1 #deﬁne DDS BOOLEAN TRUE

Deﬁnes ”true” value of DDS Boolean (p. 301) data type.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.76 DDS-Speciﬁc Primitive Types 299

5.76.2.2 #deﬁne DDS BOOLEAN FALSE

Deﬁnes ”false” value of DDS Boolean (p. 301) data type.

Examples:

HelloWorld.cxx.

5.76.3 Typedef Documentation

5.76.3.1 typedef RTICdrChar DDS Char

Deﬁnes a character data type, equivalent to IDL/CDR char.

An 8-bit quantity that encodes a single byte charater from any byte-oriented

code set.

5.76.3.2 typedef RTICdrWchar DDS Wchar

Deﬁnes a wide character data type, equivalent to IDL/CDR wchar.

An 16-bit quantity that encodes a wide character from any character set.

5.76.3.3 typedef RTICdrOctet DDS Octet

Deﬁnes an opaque byte data type, equivalent to IDL/CDR octet.

An 8-bit quantity that is guaranteed not to undergo any conversion when trans-

mitted by the middleware.

5.76.3.4 typedef RTICdrShort DDS Short

Deﬁnes a short integer data type, equivalent to IDL/CDR short.

A 16-bit signed short integer value.

5.76.3.5 typedef RTICdrUnsignedShort DDS UnsignedShort

Deﬁnes an unsigned short integer data type, equivalent to IDL/CDR unsigned

short.

A 16-bit unsigned short integer value.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

300 Module Documentation

5.76.3.6 typedef RTICdrLong DDS Long

Deﬁnes a long integer data type, equivalent to IDL/CDR long.

A 32-bit signed long integer value.

5.76.3.7 typedef RTICdrUnsignedLong DDS UnsignedLong

Deﬁnes an unsigned long integer data type, equivalent to IDL/CDR unsigned

long.

A 32-bit unsigned long integer value.

5.76.3.8 typedef RTICdrLongLong DDS LongLong

Deﬁnes an extra-long integer data type, equivalent to IDL/CDR long long.

A 64-bit signed long long integer value.

5.76.3.9 typedef RTICdrUnsignedLongLong

DDS UnsignedLongLong

Deﬁnes an unsigned extra-long data type, e quivalent to IDL/CDR unsigned

long long.

An 64-bit unsigned long long integer value.

5.76.3.10 typedef RTICdrFloat DDS Float

Deﬁnes a single-precision ﬂoating-point data type, equivalent to IDL/CDR

float.

A 32-bit ﬂoating-point value.

5.76.3.11 typedef RTICdrDouble DDS Double

Deﬁnes a double-precision ﬂoating-point data type, equivalent to IDL/CDR

double.

A 64-bit ﬂoating-point value.

5.76.3.12 typedef RTICdrLongDouble DDS LongDouble

Deﬁnes an extra-precision ﬂoating-point data type, equivalent to IDL/CDR

long double.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.76 DDS-Speciﬁc Primitive Types 301

A 128-bit ﬂoating-point value.

Since some architectures do not support long double, RTI has deﬁned character

arrays that match the expected size of this type. On systems that do have

native long double, you have to deﬁne RTI CDR SIZEOF LONG DOUBLE as

16 to map them to native types.

5.76.3.13 typedef RTICdrBo ol ean DDS Boolean

Deﬁnes a Boolean data type, equivalent to IDL/CDR boolean.

An 8-bit Boolean value that is used to denote a data item that can only take one

of the values DDS BOOLEAN TRUE (p. 298) (1) or DDS BOOLEAN -

FALSE (p. 299) (0).

5.76.3.14 typedef RTICdrEnum DDS Enum

Deﬁnes an enumerated data type.

Encoded as unsigned long value. By default, the ﬁrst enum identiﬁer has the

numeric value zero (0). Successive enum identiﬁers take ascending numeric

values, in order of declaration from left to right.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

302 Module Documentation

5.77 Time Support

Time and duration types and deﬁnes.

Classes

struct DDS Time t

Type for time representation.

struct DDS Duration t

Type for duration representation.

Deﬁnes

#deﬁne DDS TIME ZERO

The default instant in time: zero seconds and zero nanoseconds.

Functions

DDS Boolean DDS Time is zero (const struct DDS Time t

∗time)

Check if time is zero.

DDS Boolean DDS Time is invalid (const struct DDS Time t

∗time)

DDS Boolean DDS Duration is inﬁnite (const struct DDS -

Duration t ∗duration)

DDS Boolean DDS Duration is auto (const struct DDS -

Duration t ∗duration)

DDS Boolean DDS Duration is zero (const struct DDS -

Duration t ∗duration)

Variables

const DDS Long DDS TIME INVALID SEC

A sentinel indicating an invalid second of time.

const DDS UnsignedLong DDS TIME INVALID NSEC

A sentinel indicating an invalid nano-second of time.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.77 Time Support 303

struct DDS Time t DDS TIME INVALID

A sentinel indicating an invalid time.

const DDS Long DDS DURATION INFINITE SEC

An inﬁnite second period of time.

const DDS UnsignedLong DDS DURATION INFINITE -

NSEC

An inﬁnite nano-second period of time.

struct DDS Duration t DDS DURATION INFINITE

An inﬁnite period of time.

const DDS Long DDS DURATION AUTO SEC

An auto second period of time.

const DDS UnsignedLong DDS DURATION AUTO NSEC

An auto nano-second period of time.

struct DDS Duration t DDS DURATION AUTO

Duration is automatically assigned.

const DDS Long DDS DURATION ZERO SEC

A zero-length second period of time.

const DDS UnsignedLong DDS DURATION ZERO NSEC

A zero-length nano-second period of time.

struct DDS Duration t DDS DURATION ZERO

A zero-length period of time.

5.77.1 Detailed Description

Time and duration types and deﬁnes.

5.77.2 Deﬁne Documentation

5.77.2.1 #deﬁne DDS TIME ZERO

The default instant in time: zero seconds and zero nanoseconds.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

304 Module Documentation

5.77.3 Function Documentation

5.77.3.1 DDS Boolean DDS Time is zero (const struct

DDS Time t ∗ time)

Check if time is zero.

Returns:

DDS BOOLEAN TRUE (p. 298) if the given time is equal to DDS -

TIME ZERO (p. 303) or DDS BOOLEAN FALSE (p. 299) otherwise.

5.77.3.2 DDS Boolean DDS Time is invalid (const struct

DDS Time t ∗ time)

Returns:

DDS BOOLEAN TRUE (p. 298) if the given time is not valid (i.e. is

negative)

5.77.3.3 DDS Boolean DDS Duration is inﬁnite (const struct

DDS Duration t ∗ duration)

Returns:

DDS BOOLEAN TRUE (p. 298) if the given duration is of inﬁnite

length.

5.77.3.4 DDS Boolean DDS Duration is auto (const struct

DDS Duration t ∗ duration)

Returns:

DDS BOOLEAN TRUE (p. 298) if the given duration has auto value.

5.77.3.5 DDS Boolean DDS Duration is zero (const struct

DDS Duration t ∗ duration)

Returns:

DDS BOOLEAN TRUE (p. 298) if the given duration is of zero length.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.77 Time Support 305

5.77.4 Variable Documentation

5.77.4.1 const DDS Long DDS TIME INVALID SEC

A sentinel indicating an invalid second of time.

5.77.4.2 const DDS UnsignedLong DDS TIME INVALID NSEC

A sentinel indicating an invalid nano-second of time.

5.77.4.3 struct DDS Time t DDS TIME INVALID

A sentinel indicating an invalid time.

5.77.4.4 const DDS Long DDS DURATION INFINITE SEC

An inﬁnite second period of time.

5.77.4.5 const DDS UnsignedLong DDS DURATION INFINITE -

NSEC

An inﬁnite nano-second period of time.

5.77.4.6 struct DDS

Duration t DDS DURATION INFINITE

An inﬁnite period of time.

5.77.4.7 const DDS Long DDS DURATION AUTO SEC

An auto second period of time.

5.77.4.8 const DDS UnsignedLong DDS DURATION AUTO -

NSEC

An auto nano-second period of time.

5.77.4.9 struct DDS Duration t DDS DURATION AUTO

Duration is automatically assigned.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

306 Module Documentation

5.77.4.10 const DDS Long DDS DURATION ZERO SEC

A zero-length second period of time.

5.77.4.11 const DDS UnsignedLong DDS DURATION ZERO -

NSEC

A zero-length nano-second period of time.

5.77.4.12 struct DDS Duration t DDS DURATION ZERO

A zero-length period of time.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.78 GUID Support 307

5.78 GUID Support

<<eXtension>> ( p. 199) GUID type and deﬁnes.

Classes

struct DDS GUID t

Type for GUID (Global Unique Identiﬁer) representation.

Functions

DDS Boolean DDS GUID equals (const struct DDS GUID t ∗self,

const struct DDS GUID t ∗other)

Compares this GUID with another GUID for equality.

int DDS GUID compare (const struct DDS GUID t ∗self, const

struct DDS GUID t ∗other)

Compares two GUIDs.

void DDS GUID copy (struct DDS GUID t ∗self, const struct

DDS GUID t ∗other)

Copies another GUID into this GUID.

Variables

struct DDS GUID t DDS GUID AUTO

Indicates that RTI Connext should choose an appropriate virtual GUID.

struct DDS GUID t DDS GUID UNKNOWN

Unknown GUID.

5.78.1 Detailed Description

<<eXtension>> ( p. 199) GUID type and deﬁnes.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

308 Module Documentation

5.78.2 Function Documentation

5.78.2.1 DDS Boolean DDS GUID equals (const struct

DDS GUID t ∗ self, const struct DDS GUID t ∗ other)

Compares this GUID with another GUID for equality.

Parameters:

self <<in>> ( p. 200) This GUID. Cannot be NULL.

other <<in>> ( p. 200) The other GUID to be compared with this GUID.

Cannot be NULL.

Returns:

DDS BOOLEAN TRUE (p. 298) if the two GUIDs have equal values,

or DDS BOOLEAN FALSE (p. 299) otherwise.

5.78.2.2 int DDS GUID compare (const struct DDS GUID t ∗ self,

const struct DDS GUID t ∗ other)

Compares two GUIDs.

Parameters:

self <<in>> ( p. 200) GUID to compare. Cannot be NULL.

other <<in>> ( p. 200) GUID to compare. Cannot be NULL.

Returns:

If the two GUIDs are equal, the function returns 0. If self is greater than

other the function returns a positive number; otherwise, it returns a nega-

tive number.

5.78.2.3 void DDS GUID copy (struct DDS GUID t ∗ self, const

struct DDS GUID t ∗ other)

Copies another GUID into this GUID.

Parameters:

self <<in>> ( p. 200) This GUID. Cannot be NULL.

other <<in>> ( p. 200) The other GUID to be copied.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.78 GUID Support 309

5.78.3 Variable Documentation

5.78.3.1 struct DDS GUID t DDS GUID AUTO

Indicates that RTI Connext should choose an appropriate virtual GUID.

If this special value is assigned to DDS -

DataWriterProtocolQosPolicy::virtual guid (p. 536) or DDS -

DataReaderProtocolQosPolicy::virtual guid (p. 502), RTI Connext

will assign the virtual GUID automatically based on the RTPS or physical

GUID.

5.78.3.2 struct DDS GUID t DDS GUID UNKNOWN

Unknown GUID.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

310 Module Documentation

5.79 Sequence Number Support

<<eXtension>> ( p. 199) Sequence number type and deﬁnes.

Classes

struct DDS SequenceNumber t

Type for sequence number representation.

Variables

struct DDS SequenceNumber t DDS SEQUENCE NUMBER -

UNKNOWN

Unknown sequence number.

struct DDS SequenceNumber t DDS SEQUENCE NUMBER -

ZERO

Zero value for the sequence number.

struct DDS SequenceNumber t DDS SEQUENCE NUMBER -

MAX

Highest, most positive value for the sequence number.

struct DDS SequenceNumber t DDS AUTO SEQUENCE -

NUMBER

The sequence number is internally determined by RTI Connext.

5.79.1 Detailed Description

<<eXtension>> ( p. 199) Sequence number type and deﬁnes.

5.79.2 Variable Documentation

5.79.2.1 struct DDS SequenceNumber t DDS SEQUENCE -

NUMBER UNKNOWN

Unknown sequence number.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.79 Sequence Number Support 311

5.79.2.2 struct DDS SequenceNumber t DDS SEQUENCE -

NUMBER ZERO

Zero value for the sequence number.

5.79.2.3 struct DDS SequenceNumber t DDS SEQUENCE -

NUMBER MAX

Highest, most positive value for the sequence number.

5.79.2.4 struct DDS SequenceNumber t DDS AUTO -

SEQUENCE NUMBER

The sequence number is internally determined by RTI Connext.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

312 Module Documentation

5.80 Exception Codes

<<eXtension>> ( p. 199) Exception c odes.

Enumerations

enum DDS ExceptionCode t {

DDS NO EXCEPTION CODE,

DDS USER EXCEPTION CODE,

DDS SYSTEM EXCEPTION CODE,

DDS BAD PARAM SYSTEM EXCEPTION CODE,

DDS NO MEMORY SYSTEM EXCEPTION CODE,

DDS BAD TYPECODE SYSTEM EXCEPTION CODE,

DDS BADKIND USER EXCEPTION CODE,

DDS BOUNDS USER EXCEPTION CODE,

DDS IMMUTABLE TYPECODE SYSTEM EXCEPTION -

CODE = 8,

DDS BAD MEMBER NAME USER EXCEPTION CODE = 9,

DDS BAD MEMBER ID USER EXCEPTION CODE = 10 }

Error codes used by the DDS TypeCode ( p. 992) class.

5.80.1 Detailed Description

<<eXtension>> ( p. 199) Exception c odes.

These exceptions are used for error handling by the Type Code Support

(p. 56) API.

5.80.2 Enumeration Type Documentation

5.80.2.1 enum DDS ExceptionCode t

Error codes used by the DDS TypeCode (p. 992) c lass.

Exceptions are modeled via a special parameter passed to the operations.

Enumerator:

DDS NO EXCEPTION CODE No failure occurred.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.80 Exception Codes 313

DDS USER EXCEPTION CODE User exception.

This class is based on a similar class in CORBA.

DDS SYSTEM EXCEPTION CODE System exception.

This class is based on a similar class in CORBA.

DDS BAD PARAM SYSTEM EXCEPTION CODE Exception

thrown when a parameter passed to a call is considered illegal.

DDS NO MEMORY SYSTEM EXCEPTION CODE Exception

thrown when there is not enough memory for a dynamic memory

allocation.

DDS BAD TYPECODE SYSTEM EXCEPTION CODE

Exception thrown when a malformed type code is found (for example,

a type code with an invalid TCKind value).

DDS BADKIND USER EXCEPTION CODE The exception

BadKind is thrown when an inappropriate operation is invoked on a

TypeCode object.

DDS BOUNDS USER EXCEPTION CODE A user exception

thrown when a parameter is not within the legal bounds.

DDS IMMUTABLE TYPECODE SYSTEM EXCEPTION CODE

An attempt was made to modify a DDS TypeCode (p. 992) that

was received from a remote object.

The built-in publication and subscription readers provide access to

information about the remote DDSDataWriter (p. 1113) and DDS-

DataReader (p. 1087) entities in the distributed system. Among

other things, the data from these built-in readers contains the DDS -

TypeCode (p. 992) for these entities. Modifying this received DDS -

TypeCode (p. 992) is not permitted.

DDS BAD MEMBER NAME USER EXCEPTION CODE The

speciﬁed DDS TypeCode (p. 992) member name is invalid.

This failure can occur, for example, when querying a ﬁeld by name

when no such name is deﬁned in the type.

See also:

DDS BAD MEMBER ID USER EXCEPTION CODE

(p. 313)

DDS BAD MEMBER ID USER EXCEPTION CODE The

speciﬁed DDS TypeCode (p. 992) member ID is invalid.

This failure can occur, for example, when querying a ﬁeld by ID when

no such ID is deﬁned in the type.

See also:

DDS BAD MEMBER NAME USER EXCEPTION -

CODE (p. 313)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

314 Module Documentation

5.81 Return Codes

Types of return codes.

Enumerations

enum DDS ReturnCode t {

DDS RETCODE OK,

DDS RETCODE ERROR,

DDS RETCODE UNSUPPORTED,

DDS RETCODE BAD PARAMETER,

DDS RETCODE PRECONDITION NOT MET,

DDS RETCODE OUT OF RESOURCES,

DDS RETCODE NOT ENABLED,

DDS RETCODE IMMUTABLE POLICY,

DDS RETCODE INCONSISTENT POLICY,

DDS RETCODE ALREADY DELETED,

DDS RETCODE TIMEOUT,

DDS RETCODE NO DATA,

DDS RETCODE ILLEGAL OPERATION }

Type for return codes.

5.81.1 Detailed Description

Types of return codes.

5.81.2 Standard Return Codes

Any operation with return type DDS ReturnCode t (p. 315) may re -

turn DDS RETCODE OK (p. 315) DDS R ETCODE ERROR (p. 315)

or DDS RETCODE ILLEGAL OPERATION (p. 316). Any operation

that takes one or more input parameters may additionally return DDS -

RETCODE BAD PARAMETER (p. 315). Any operation on an object

created from any of the factories may additionally return DDS RETCODE -

ALREADY DELETED (p. 316). Any operation that is stated as optional

may additionally return DDS RETCODE UNSUPPORTED (p. 315).

Thus, the standard return codes are:

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.81 Return Codes 315

DDS RETCODE ERROR (p. 315)

DDS RETCODE ILLEGAL OPERATION (p. 316)

DDS RETCODE ALREADY DELETED (p. 316)

DDS RETCODE BAD PARAMETER (p. 315)

DDS RETCODE UNSUPPORTED (p. 315)

Operations that may return any of the additional return codes will state so

explicitly.

5.81.3 Enumeration Type Documentation

5.81.3.1 enum DDS ReturnCode t

Type for return codes.

Errors are modeled as operation return codes of this type.

Enumerator:

DDS RETCODE OK Successful return.

DDS RETCODE ERROR Generic, unspeciﬁed error.

DDS RETCODE UNSUPPORTED Unsupported operation. Can

only returned by operations that are unsupported.

DDS RETCODE BAD PARAMETER Illegal parameter value.

The value of the parameter that is passed in has llegal value. Things

that falls into this category includes NULL parameters and parameter

values that are out of range.

DDS RETCODE PR ECONDITION NOT MET A pre-condition

for the operation was not met.

The system is not in the expected state when the function is called,

or the parameter itself is not in the expected state when the function

is called.

DDS RETCODE OUT OF RESOURCES RTI Connext ran out of

the resources needed to complete the operation.

DDS RETCODE NOT ENABLED Operation invoked on a

DDSEntity (p. 1253) that is not yet enabled.

DDS RETCODE IMMUTABLE POLICY Application attempted

to modify an immutable QoS policy.

DDS RETCODE INCONSISTENT POLICY Application speci-

ﬁed a set of QoS policies that are not consistent with each other.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

316 Module Documentation

DDS RETCODE ALREADY DELETED The object target of this

operation has already been deleted.

DDS RETCODE TIMEOUT The operation timed out.

DDS RETCODE NO DATA Indicates a transient situation where the

operation did not return any data but there is no inherent error.

DDS RETCODE ILLEGAL OPERATION The operation was

called under improper circumstances.

An operation was invoked on an inappropriate object or at an inap-

propriate time. This return code is similar to DDS RETCODE -

PRECONDITION NOT MET (p. 315), except that there is no

precondition that could be changed to make the operation succeed.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.82 Status Kinds 317

5.82 Status Kinds

Kinds of communication status.

Deﬁnes

#deﬁne DDS STATUS MASK NONE

No bits are set.

#deﬁne DDS STATUS MASK ALL

All bits are set.

Typedefs

typedef DDS UnsignedLong DDS StatusMask

A bit-mask (list) of concrete status types, i.e. DDS StatusKind ( p. 322)[].

Enumerations

enum DDS StatusKind {

DDS INCONSISTENT TOPIC STATUS,

DDS OFFERED DEADLINE MISSED STATUS,

DDS REQUESTED DEADLINE MISSED STATUS,

DDS OFFERED INCOMPATIBLE QOS STATUS,

DDS REQUESTED INCOMPATIBLE QOS STATUS,

DDS SAMPLE LOST STATUS,

DDS SAMPLE REJECTED STATUS,

DDS DATA ON READERS STATUS,

DDS DATA AVAILABLE STATUS,

DDS LIVELINESS LOST STATUS,

DDS LIVELINESS CHANGED STATUS,

DDS PUBLICATION MATCHED STATUS,

DDS SUBSCRIPTION MATCHED STATUS ,

DDS DATA WRITER INSTANCE REPLACED STATUS,

DDS RELIABLE WRITER CACHE CHANGED STATUS,

DDS RELIABLE READER ACTIVITY CHANGED STATUS,

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

318 Module Documentation

DDS DATA WRITER CACHE STATUS,

DDS DATA WRITER PROTOCOL STATUS,

DDS DATA READER CACHE STATUS,

DDS DATA READER PROTOCOL STATUS }

Type for status kinds.

5.82.1 Detailed Description

Kinds of communication status.

Entity:

DDSEntity (p. 1253)

QoS:

QoS Policies (p. 331)

Listener:

DDSListener (p. 1318)

Each concrete DDSEntity (p. 1253) is associated with a set of Status objects

whose value represents the communication status of that entity. Each sta-

tus value can be accessed with a corresponding method on the DDSEntity

(p. 1253).

When these status values change, the corresponding DDSStatusCondition

(p. 1376) objects are activated and the proper DDSListener (p. 1318) objects

are invoked to asynchronously inform the application.

An application is notiﬁed of communication status by means of the DDSLis-

tener (p. 1318) or the DDSWaitSet (p. 1433) / DDSCondition (p. 1075)

mechanism. The two mechanisms may be combined in the application (e.g.,

using DDSWaitSet (p. 1433) (s) / DDSCondition (p. 1075) (s) to access the

data and DDSListener (p. 1318) (s) to be warned asynchronously of erroneous

communication statuses).

It is likely that the application will choose one or the other mechanism for each

particular communication status (not both). However, if both mechanisms are

enabled, then the DDSListener (p. 1318) mechanism is used ﬁrst and then the

DDSWaitSet (p. 1433) objects are signalled.

The statuses may be classiﬁed into:

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.82 Status Kinds 319

read communication statuses: i.e., those that are related to arrival of data,

namely DDS DATA ON READERS STATUS (p. 324) and DDS -

DATA AVAILABLE STATUS (p. 324).

plain communication statuses: i.e., all the others.

Read communication statuses are treated slightly diﬀerently than the others be -

cause they don’t change independently. In other words, at least two changes will

appear at the same time (DDS DATA ON READERS STATUS (p. 324)

and DDS DATA AVAILABLE STATUS (p. 324)) and even several of the

last kind may be part of the set. This ’grouping’ has to be communicated to

the application.

For each plain communication status, there is a corresponding structure to hold

the status value. These values contain the information related to the change of

status, as well as information related to the statuses themselves (e.g., contains

cumulative counts).

5.82.2 Changes in Status

Associated with each one of an DDSEntity (p. 1253)’s communication status

is a logical StatusChangedFlag. This ﬂag indicates whether that particular

communication status has changed since the last time the status was read by

the application. The way the status changes is slightly diﬀerent for the Plain

Communication Status and the Read Communication status.

5.82.2.1 Changes in plain communication status

For the plain communication status, the StatusChangedFlag ﬂag is initially

set to FALSE. It becomes TRUE whenever the plain communication status

changes and it is reset to DDS BOOLEAN FALSE (p. 299) each time the

application accesses the plain communication status via the proper get <plain

communication status>() operation on the DDSEntity (p. 1253).

The communication status is also reset to FALSE whenever the associated lis-

tener operation is called as the listener implicitly accesses the status which is

passed as a parameter to the operation. The fact that the status is reset prior

to calling the listener means that if the application calls the get <plain commu-

nication s tatus> from inside the listener it will see the status already reset.

An exception to this rule is when the associated listener is the ’nil’ listener. The

’nil’ listener is treated as a NOOP and the act of calling the ’nil’ listener does

not reset the communication status.

For example, the value of the StatusChangedFlag associated with the

DDS REQUESTED DEADLINE MISSED STATUS (p. 323) will be-

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

320 Module Documentation

come TRUE each time new deadline occurs (which increases the DDS -

RequestedDeadlineMissedStatus::total count (p. 875) ﬁeld). The value

changes to FALSE when the application accesses the s tatus via the

corresponding DDSDataReader::get requested deadline missed status

(p. 1099) method on the proper Entity

5.82.2.2 Changes in read communication status

For the read communication status, the StatusChangedFlag ﬂag is initially set

to FALSE. The StatusChangedFlag becomes TRUE when either a data-sample

arrive s or else the DDS ViewStateKind (p. 113), DDS SampleStateKind

(p. 111), or DDS InstanceStateKind (p. 116) of any existing sample changes

for any reason other than a call to FooDataReader::read (p. 1447), Foo-

DataReader::take (p. 1448) or their variants. Speciﬁcally any of the following

events will cause the StatusChangedFlag to become TRUE:

The arrival of new data.

A change in the DDS InstanceStateKind (p. 116) of a contained in-

stance. This can be caused by either:

– The arrival of the notiﬁcation that an instance has be en disposed by:

the DDSDataWriter (p. 1113) that owns it if OWNERSHIP

(p. 355) QoS kind= DDS EXCLUSIVE OWNERSHIP -

QOS (p. 356)

or by any DDSDataWriter (p. 1113) if OWNERSHIP

(p. 355) QoS kind= DDS SHARED OWNERSHIP QOS

(p. 356)

– The loss of liveliness of the DDSDataWriter (p. 1113) of an instance

for w hich there is no other DDSDataWriter (p. 1113).

– The arrival of the notiﬁcation that an instance has been unregistered

by the only DDSDataWriter (p. 1113) that is known to be writing

the instance.

Depending on the kind of StatusChangedFlag, the ﬂag transitions to FALSE

again as follows:

The DDS DATA AVAILABLE STATUS (p. 324)

StatusChangedFlag becomes FALSE when either the corresponding

listener operation (on data available) is called or the read or take oper-

ation (or their variants) is called on the associated DDSDataReader

(p. 1087).

The DDS DATA ON READERS STATUS (p. 324)

StatusChangedFlag becomes FALSE when any of the following

events occurs:

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.82 Status Kinds 321

– The corresponding listener operation (on data on readers) is called.

– The on data available listener operation is called on any DDS-

DataReader (p. 1087) belonging to the DDSSubscriber (p. 1390).

– The read or take operation (or their variants) is called on any DDS-

DataReader (p. 1087) belonging to the DDSSubscriber (p. 1390).

See also:

DDSListener (p. 1318)

DDSWaitSet (p. 1433), DDSCondition (p. 1075)

5.82.3 Deﬁne Documentation

5.82.3.1 #deﬁne DDS STATUS MASK NONE

No bits are set.

Examples:

HelloWorld publisher.cxx, and HelloWorld subscriber.cxx.

5.82.3.2 #deﬁne DDS STATUS MASK ALL

All bits are set.

Examples:

HelloWorld subscriber.cxx.

5.82.4 Typedef Documentation

5.82.4.1 typedef DDS UnsignedLong DDS StatusMask

A bit-mask (list) of concrete status types, i.e. DDS StatusKind (p. 322)[].

The bit-mask is an eﬃcient and compact representation of a ﬁxed-length list of

DDS StatusKind (p. 322) values.

Bits in the mask correspond to diﬀerent statuses. You can choose which changes

in status will trigger a callback by se tting the corresponding status bits in this

bit-mask and installing callbacks for each of those statuses.

The bits that are true indicate that the listener will be called back for changes

in the corresponding status.

For example:

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

322 Module Documentation

DDS_StatusMask mask = DDS_REQUESTED_DEADLINE_MISSED_STATUS |

DDS_DATA_AVAILABLE_STATUS;

datareader->set_listener(listener, mask);

DDS_StatusMask mask = DDS_REQUESTED_DEADLINE_MISSED_STATUS |

DDS_DATA_AVAILABLE_STATUS;

datareader = subscriber->create_datareader(topic,

DDS_DATAREADER_QOS_DEFAULT,

listener, mask);

5.82.5 Enumeration Type Documentation

5.82.5.1 enum DDS StatusKind

Type for status kinds.

Each concrete DDSEntity (p. 1253) is associated with a set of ∗Status objects

whose values represent the communication status of that DDSEntity (p. 1253).

The communication statuses whose changes can be communicated to the appli-

cation depend on the DDSEntity (p. 1253).

Each status value can be accessed with a corresponding method on the DDSEn-

tity (p. 1253). The changes on these status values cause activation of the cor-

responding DDSStatusCondition (p. 1376) objects and trigger invocation of

the proper DDSListener (p. 1318) objects to asynchronously inform the appli-

cation.

See also:

DDSEntity (p. 1253), DDSStatusCondition (p. 1376), DDSListener

(p. 1318)

Enumerator:

DDS INCONSISTENT TOPIC STATUS Another topic exists with

the same name but diﬀerent characteristics.

Entity:

DDSTopic (p. 1419)

Status:

DDS InconsistentTopicStatus (p. 762)

Listener:

DDSTopicListener (p. 1430)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.82 Status Kinds 323

DDS OFFERED DEADLINE MISSED STATUS The deadline

that the DDSDataWriter (p. 1113) has committed through its

DDS DeadlineQosPolicy (p. 567) was not respected for a sp ec iﬁc

instance.

Entity:

DDSDataWriter (p. 1113)

QoS:

DEADLINE (p. 353)

Status:

DDS OﬀeredDeadlineMissedStatus (p. 803)

Listener:

DDSDataWriterListener (p. 1133)

DDS REQUESTED DEADLINE MISSED STATUS The dead-

line that the DDSDataReader (p. 1087) was expecting through its

DDS DeadlineQosPolicy (p. 567) was not respected for a sp ec iﬁc

instance.

Entity:

DDSDataReader (p. 1087)

QoS:

DEADLINE (p. 353)

Status:

DDS RequestedDeadlineMissedStatus (p. 875)

Listener:

DDSDataReaderListener (p. 1108)

DDS OFFERED INCOMPATIBLE QOS STATUS A QosPolicy

value was incompatible with what was requested.

Entity:

DDSDataWriter (p. 1113)

Status:

DDS OﬀeredIncompatibleQosStatus (p. 805)

Listener:

DDSDataWriterListener (p. 1133)

DDS REQUESTED INCOMPATIBLE QOS STATUS A

QosPolicy value was incompatible with what is oﬀered.

Entity:

DDSDataReader (p. 1087)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

324 Module Documentation

Status:

DDS RequestedIncompatibleQosStatus (p. 877)

Listener:

DDSDataReaderListener (p. 1108)

DDS SAMPLE LOST STATUS A sample has been lost (i.e. was

never received).

Entity:

DDSDataReader (p. 1087)

Status:

DDS SampleLostStatus (p. 923)

Listener:

DDSDataReaderListener (p. 1108)

DDS SAMPLE REJECTED STATUS A (received) sample has been

rejected.

Entity:

DDSDataReader (p. 1087)

QoS:

RESOURCE LIMITS (p. 371)

Status:

DDS SampleRejectedStatus (p. 925)

Listener:

DDSDataReaderListener (p. 1108)

DDS DATA ON READERS STATUS New data is available.

Entity:

DDSSubscriber (p. 1390)

Listener:

DDSSubscriberListener (p. 1414)

DDS DATA AVAILABLE STATUS One or more new data samples

have been received.

Entity:

DDSDataReader (p. 1087)

Listener:

DDSDataReaderListener (p. 1108)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.82 Status Kinds 325

DDS LIVELINESS LOST STATUS The liveliness that the DDS-

DataWriter (p. 1113) has committed to through its DDS -

LivelinessQosPolicy (p. 779) was not respected, thus DDS-

DataReader (p. 1087) entities will consider the DDSDataWriter

(p. 1113) as no longer alive.

Entity:

DDSDataWriter (p. 1113)

QoS:

LIVELINESS (p. 358)

Status:

DDS LivelinessLostStatus (p. 777)

Listener:

DDSDataWriterListener (p. 1133)

DDS LIVELINESS CHANGED STATUS The liveliness of one or

more DDSDataWriter (p. 1113) that were writing instances read

through the DDSDataReader (p. 1087) has changed. Some DDS-

DataWriter (p. 1113) have become alive or not alive.

Entity:

DDSDataReader (p. 1087)

QoS:

LIVELINESS (p. 358)

Status:

DDS LivelinessChangedStatus (p. 775)

Listener:

DDSDataReaderListener (p. 1108)

DDS PUBLICATION MATCHED STATUS The DDS-

DataWriter (p. 1113) has found DDSDataReader (p. 1087)

that matches the DDSTopic (p. 1419) and has compatible QoS.

Entity:

DDSDataWriter (p. 1113)

Status:

DDS PublicationMatchedStatus (p. 848)

Listener:

DDSDataWriterListener (p. 1133)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

326 Module Documentation

DDS SUBSCRIPTION MATCHED STATUS The DDS-

DataReader (p. 1087) has found DDSDataWriter (p. 1113)

that matches the DDSTopic (p. 1419) and has compatible QoS.

Entity:

DDSDataReader (p. 1087)

Status:

DDS SubscriptionMatchedStatus (p. 945)

Listener:

DDSDataReaderListener (p. 1108)

DDS DATA WRITER INSTANCE REPLACED STATUS

<<eXtension>> ( p. 199) A DDSDataWriter (p. 1113) instance

has been replaced

Enables a DDSDataWriter (p. 1113) callback that is called when an

instance in the writer queue is replaced.

Entity:

DDSDataWriter (p. 1113)

Listener:

DDSDataWriterListener (p. 1133)

DDS RELIABLE WRITER CACHE CHANGED STATUS

<<eXtension>> ( p. 199) The number of unacknowledged samples

in a reliable writer’s cache has changed such that it has reached a

pre-deﬁned trigger point.

This status is considered changed at the following times: the

cache is empty (i.e. contains no unacknowledge samples),

full (i.e. the sample count has reached the value speciﬁed

in DDS ResourceLimitsQosPolicy::max samples (p. 881)),

or the number of samples has reached a high (see DDS -

RtpsReliableWriterProtocol t::high watermark (p. 892)) or

low (see DDS RtpsReliableWriterProtocol t::low watermark

(p. 892)) watermark.

Entity:

DDSDataWriter (p. 1113)

Status:

DDS ReliableWriterCacheChangedStatus (p. 871)

Listener:

DDSDataWriterListener (p. 1133)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.82 Status Kinds 327

DDS RELIABLE READER ACTIVITY CHANGED STATUS

<<eXtension>> ( p. 199) One or more reliable readers has become

active or inactive.

A reliable reader is considered active by a reliable writer with which

it is matched if that reader acknowledges the samples it has been

sent in a timely fashion. For the deﬁnition of ”timely” in this

case, see DDS RtpsReliableWriterProtocol t (p. 889) and DDS -

ReliableReaderActivityChangedStatus (p. 869).

See also:

DDS RtpsReliableWriterProtocol t (p. 889)

DDS ReliableReaderActivityChangedStatus (p. 869)

DDS DATA WRITER CACHE STATUS <<eXtension>>

( p. 199) The s tatus of the writer’s cache.

DDS DATA WRITER PROTOCOL STATUS <<eXtension>>

( p. 199) The s tatus of a writer’s internal protocol related metrics

The status of a writer’s internal protocol related metrics, like the num-

ber of samples pushed, pulled, ﬁltered; and status of wire protocol

traﬃc.

DDS DATA READER CACHE STATUS <<eXtension>>

( p. 199) The s tatus of the reader’s cache.

DDS DATA READER PROTOCOL STATUS <<eXtension>>

( p. 199) The s tatus of a reader’s internal protocol related metrics

The status of a reader’s internal protocol related metrics, like the num-

ber of samples received, ﬁltered, rejected; and status of wire protocol

traﬃc.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

328 Module Documentation

5.83 Thread Settings

The properties of a thread of execution.

Classes

struct DDS ThreadSettings t

The properties of a thread of execution.

Deﬁnes

#deﬁne DDS THREAD SETTINGS KIND MASK DEFAULT

The mask of default thread options.

Typedefs

typedef DDS UnsignedLong DDS ThreadSettingsKindMask

A mask of which each bit is taken from DDS ThreadSettingsKind ( p. 329).

Enumerations

enum DDS ThreadSettingsKind {

DDS THREAD SETTINGS FLOATING POINT,

DDS THREAD SETTINGS STDIO,

DDS THREAD SETTINGS REALTIME PRIORITY,

DDS THREAD SETTINGS PRIORITY ENFORCE }

A collection of ﬂags used to conﬁgure threads of execution.

enum DDS ThreadSettingsCpuRotationKind {

DDS THREAD SETTINGS CPU NO ROTATION,

DDS THREAD SETTINGS CPU RR ROTATION }

Determines how DDS ThreadSettings t::cpu list ( p. 951) aﬀects proces-

sor aﬃnity for thread-related QoS policies that apply to multiple threads.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.83 Thread Settings 329

5.83.1 Detailed Description

The properties of a thread of execution.

5.83.2 Deﬁne Documentation

5.83.2.1 #deﬁne DDS THREAD SETTINGS KIND MASK -

DEFAULT

The mask of default thread options.

5.83.3 Typedef Documentation

5.83.3.1 typedef DDS UnsignedLong DDS -

ThreadSettingsKindMask

A mask of which each bit is taken from DDS ThreadSettingsKind (p. 329).

See also:

DDS ThreadSettings t (p. 950)

5.83.4 Enumeration Type Documentation

5.83.4.1 enum DDS ThreadSettingsKind

A collection of ﬂags used to conﬁgure threads of execution.

Not all of these options may be relevant for all operating systems.

See also:

DDS ThreadSettingsKindMask (p. 329)

Enumerator:

DDS THREAD SETTINGS FLOATING POINT Code executed

within the thread may perform ﬂoating point operations.

DDS THREAD SETTINGS STDIO Code executed within the

thread m ay access standard I/O.

DDS THREAD SETTINGS REALTIME PRIORITY The

thread w ill be schedule on a real-time basis.

DDS THREAD SETTINGS PRIORITY ENFORCE Strictly en-

force this thread’s priority.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

330 Module Documentation

5.83.4.2 enum DDS ThreadSettingsCpuRotationKind

Determines how DDS ThreadSettings t::cpu list (p. 951) aﬀects processor

aﬃnity for thread-related QoS policies that apply to multiple threads.

5.83.5 Controlling CPU Core Aﬃnity for RTI Threads

Most thread-related QoS settings apply to a single thread (such as for the

DDS EventQosPolicy (p. 739), DDS DatabaseQosPolicy (p. 495), and

DDS AsynchronousPublisherQosPolicy (p. 466)). However, the thread

settings in the DDS ReceiverPoolQosPolicy (p. 862) control every receive

thread created. In this case, there are several schemes to map M threads to N

processors; the rotation kind controls which scheme is used.

If DDS ThreadSettings t::cpu list (p. 951) is empty, the rotation is irrel-

evant s ince no aﬃ nity adjustment will occur. Suppose instead that DDS -

ThreadSettings t::cpu list (p. 951) = {0, 1} and that the middleware creates

three receive threads: {A, B, C}. If DDS ThreadSettings t::cpu rotation

(p. 951) is DDS THREAD SETTINGS CPU NO ROTATION (p. 330),

threads A, B and C will have the same processor aﬃnities (0-1), and the OS

will c ontrol thread scheduling within this bound. It is common to denote CPU

aﬃnities as a bitmask, where set bits represent allowed processors to run on.

This mask is printed in hex, so a CPU core aﬃnity of 0-1 can be represented

by the mask 0x3.

If DDS ThreadSettings t::cpu rotation (p. 951) is DDS THREAD -

SETTINGS CPU RR ROTATION (p. 330), each thread will be assigned

in round-robin fashion to one of the processors in DDS ThreadSettings -

t::cpu list (p. 951); perhaps thread A to 0, B to 1, and C to 0. Note that the

order in which internal middleware threads spawn is unspeciﬁed.

Not all of these options may be relevant for all operating systems.

Enumerator:

DDS THREAD SETTINGS CPU NO ROTATION Any thread

controlled by this QoS can run on any listed processor, as determined

by OS scheduling.

DDS THREAD SETTINGS CPU RR ROTATION Threads con-

trolled by this QoS will be assigned one processor from the list in

round-robin order.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.84 QoS Poli cies 331

5.84 QoS Policies

Quality of Service (QoS) policies.

Modules

USER DATA

Attaches a buﬀer of opaque data that is distributed by means of Built-in

Topics ( p. 42) during discovery.

TOPIC DATA

Attaches a buﬀer of opaque data that is distributed by means of Built-in

Topics ( p. 42) during discovery.

GROUP DATA

Attaches a buﬀer of opaque data that is distributed by means of Built-in

Topics ( p. 42) during discovery.

DURABILITY

This QoS policy speciﬁes whether or not RTI Connext will store and de-

liver previously published data samples to new DDSDataReader ( p. 1087)

entities that join the network later.

PRESENTATION

Speciﬁes how the samples representing changes to data instances are pre-

sented to a subscribing application.

DEADLINE

Expresses the maximum duration (deadline) within which an instance is ex-

pected to be updated.

LATENCY BUDGET

Provides a hint as to the maximum acceptable delay from the time the data

is written to the time it is received by the subscribing applications.

OWNERSHIP

Speciﬁes whether it is allowed for multiple DDSDataWriter ( p. 1113) (s)

to write the same instance of the data and if so, how these modiﬁcations

should be arbitrated.

OWNERSHIP STRENGTH

Speciﬁes the value of the strength used to arbitrate among multiple DDS-

DataWriter ( p. 1113) objects that attempt to modify the same instance of

a data type (identiﬁed by DDSTopic ( p. 1419) + key).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

332 Module Documentation

LIVELINESS

Speciﬁes and conﬁgures the mec hanism that allows DDSDataReader

( p. 1087) entities to detect when DDSDataWriter ( p. 1113) entities be-

come disconnected or ”dead.”.

TIME BASED FILTER

Filter that allows a DDSDataReader ( p. 1087) to specify that it is inter-

ested only in (potentially) a subset of the values of the data.

PARTITION

Set of strings that introduces a logical partition among the topics visible by

a DDSPublisher ( p. 1346) and a DDSSubscriber ( p. 1390).

RELIABILITY

Indicates the level of reliability oﬀered/requested by RTI Connext.

DESTINATION ORDER

Controls the criteria used to determine the logical order among changes made

by DDSPublisher ( p. 1346) entities to the same instance of data (i.e.,

matching DDSTopic ( p. 1419) and key).

HISTORY

Speciﬁes the behavior of RTI Connext in the case where the value of an

instance changes (one or more times) before it can be successfully communi-

cated to one or more existing subscribers.

DURABILITY SERV ICE

Various settings to conﬁgure the external RTI Persistence Service used by

RTI Connext for DataWriters with a DDS DurabilityQosPolicy ( p. 614)

setting of DDS PERSISTENT DURABILITY QOS ( p. 349) or DDS -

TRANSIENT DURABILITY QOS ( p. 349).

RESOURCE LIMITS

Controls the amount of physical memory allocated for DDS entities, if dy-

namic allocations are allowed, and how they occur. Also controls memory

usage among diﬀerent instance values for keyed topics.

TRANSPORT PRIORITY

This QoS policy allows the application to take advantage of transports that

are capable of sending messages with diﬀerent priorities.

LIFESPAN

Speciﬁes how long the data written by the DDSDataWriter ( p. 1113) is

considered valid.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.84 QoS Poli cies 333

WRITER DATA LIFECYCLE

Controls how a DataWriter handles the lifecycle of the instances (keys) that

it is registered to manage.

READER DATA LIFECYCLE

Controls how a DataReader manages the lifecycle of the data that it has

received.

ENTITY FACTORY

A QoS pol icy for all DDSEntity ( p. 1253) types that can act as factories

for one or more other DDSEntity ( p. 1253) types.

Extended Qos Support

<<eXtension>> (p. 199) Types and deﬁnes used in extended QoS policies.

TRANSPORT SELECTION

<<eXtension>> (p. 199) Speciﬁes the physical transports that a DDS-

DataWriter ( p. 1113) or DDSDataReader ( p. 1087) may use to send or

receive data.

TRANSPORT UNICAST

<<eXtension>> (p. 199) Speciﬁes a subset of transports and a port number

that can be used by an Entity to receive data.

TRANSPORT MULTICAST

<<eXtension>> (p. 199) Speciﬁes the multicast address on which a DDS-

DataReader ( p. 1087) wants to receive its data. It can also specify a port

number, as well as a subset of the available (at the DDSDomainPartici-

pant ( p. 1139) level) transports with which to receive the multicast data.

TRANSPORT MULTICAST MAPPING

<<eXtension>> (p. 199) Speciﬁes a list of topic expressions and addresses

that can be used by an Entity with a speciﬁc topic name to receive data.

DISCOVERY

<<eXtension>> (p. 199) Speciﬁes the attributes required to discover par-

ticipants in the domain.

TRANSPORT BUILTIN

<<eXtension>> (p. 199) Speciﬁes which built-in transports are used.

WIRE PROTOCOL

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

334 Module Documentation

<<eXtension>> (p. 199) Speciﬁes the wire protocol related attributes for

the DDSDomainParticipant ( p. 1139).

DATA READER RESOURCE LIMITS

<<eXtension>> (p. 199) Various settings that conﬁgure how DataReaders

allocate and use physical memory for internal resources.

DATA WRITER RESOURCE LIMITS

<<eXtension>> (p. 199) Various settings that conﬁgure how a DDS-

DataWriter ( p. 1113) allocates and uses physical memory for internal re-

sources.

DATA READER PROTOCOL

<<eXtension>> (p. 199) Speciﬁes the DataReader-speciﬁc protocol QoS.

DATA WRITER PROTOCOL

<<eXtension>> (p. 199) Along with DDS WireProtocolQosPolicy

( p. 1059) and DDS DataReaderProtocolQosPolicy ( p. 501), this QoS

policy conﬁgures the DDS on-the-network protocol (RTPS).

SYSTEM RESOURCE LIMITS

<<eXtension>> (p. 199) Conﬁgures DomainParticipant-independent re-

sources used by RTI Connext.

DOMAIN PARTICIPANT RESOURCE LIMITS

<<eXtension>> (p. 199) Various settings that conﬁgure how a DDSDo-

mainParticipant ( p. 1139) allocates and uses physical memory for internal

resources, including the maximum sizes of various properties.

EVENT

<<eXtension>> (p. 199) Conﬁgure s the internal thread in a DomainPar-

ticipant that handles timed events.

DATABASE

<<eXtension>> (p. 199) Various threads and resource limits settings used

by RTI Connext to control its internal database.

RECEIVER POOL

<<eXtension>> (p. 199) Conﬁgures threads used by RTI Connext to re-

ceive and process data from transports (for example, UDP sockets).

PUBLISH MODE

<<eXtension>> (p. 199) Speciﬁes how RTI Connext sends application data

on the network. This QoS policy can be used to tell RTI Connext to use its

own thread to send data, instead of the user thread.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.84 QoS Poli cies 335

DISCOVERY CONFIG

<<eXtension>> (p. 199) Speciﬁes the discovery conﬁguration QoS.

ASYNCHRONOUS PUBLISHER

<<eXtension>> (p. 199) Speciﬁes the asynchronous publishing settings of

the DDSPublisher ( p. 1346) instances.

TYPESUPPORT

<<eXtension>> (p. 199) Allows you to attach application-speciﬁc values

to a DataWriter or DataReader that are passed to the serialization or dese-

rialization routine of the associated data type.

EXCLUSIVE AREA

<<eXtension>> (p. 199) Conﬁgures multi-thread concurrency and dead-

lock prevention capabilities.

BATCH

<<eXtension>> (p. 199) Batch QoS policy used to enable batching in

DDSDataWriter ( p. 1113) instances.

TYPE CONSISTENCY ENFORCEMENT

Deﬁnes the rules for determining whether the type used to publish a given

topic is consistent with that used to subscribe to it.

LOCATORFILTER

<<eXtension>> (p. 199) The QoS policy used to report the

conﬁguration of a MultiChannel DataWriter as part of DDS -

PublicationBuiltinTopicData ( p. 839).

MULTICHANNEL

<<eXtension>> (p. 199) Conﬁgures the ability of a DataWriter to send

data on diﬀerent multicast groups (addresses) based on the value of the data.

PROPERTY

<<eXtension>> (p. 199) Store s name/value (string) pairs that can be used

to conﬁgure certain parameters of RTI Connext that are not exposed through

formal QoS policies. Can also be used to store and propagate application-

speciﬁc name/value pairs that can be retrieved by user code during discovery.

AVAILABILITY

<<eXtension>> (p. 199) Conﬁgures the availability of data.

ENTITY NAME

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

336 Module Documentation

<<eXtension>> (p. 199) Assigns a name to a DDSDomainParticipant

( p. 1139). This name will be visible during the discovery process and in RTI

tools to help you visualize and debug your system.

PROFILE

<<eXtension>> (p. 199) Conﬁgures the way that XML documents con-

taining QoS proﬁles are loaded by RTI Connext.

LOGGING

<<eXtension>> (p. 199) Conﬁgures the RTI Connext logging facility.

Classes

struct DDS QosPolicyCount

Type to hold a counter for a DDS QosPolicyId t ( p. 341).

struct DDS QosPolicyCountSeq

Declares IDL sequence < DDS QosPolicyCount ( p. 857) >.

Deﬁnes

#deﬁne DDS QOS POLICY COUNT

Number of QoS policies in DDS QosPolicyId t ( p. 341).

Enumerations

enum DDS QosPolicyId t {

DDS INVALID QOS POLICY ID,

DDS USERDATA QOS POLICY ID,

DDS DURABILITY QOS POLICY ID,

DDS PRESENTATION QOS POLICY ID,

DDS DEADLINE QOS POLICY ID,

DDS LATENCYBUDGET QOS POLICY ID,

DDS OWNERSHIP QOS POLICY ID,

DDS OWNERSHIPSTRENGTH QOS POLICY ID,

DDS LIVELINESS QOS POLICY ID,

DDS TIMEBASEDFILTER QOS POLICY ID,

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.84 QoS Poli cies 337

DDS PARTITION QOS POLICY ID,

DDS RELIABILITY QOS POLICY ID,

DDS DESTINATIONORDER QOS POLICY ID,

DDS HISTORY QOS POLICY ID,

DDS RESOURCELIMITS QOS POLICY ID,

DDS ENTITYFACTORY QOS POLICY ID,

DDS WRITERDATALIFECYCLE QOS POLICY ID,

DDS READERDATALIFECYCLE QOS POLICY ID,

DDS TOPICDATA QOS POLICY ID,

DDS GROUPDATA QOS POLICY ID,

DDS TRANSPORTPR IORITY QOS POLICY ID,

DDS LIFESPAN QOS POLICY ID,

DDS DURABILITYSERVICE QOS POLICY ID,

DDS TYPE CONSISTENCY ENFORCEMENT QOS -

POLICY ID,

DDS WIREPROTOCOL QOS POLICY ID,

DDS DISCOVERY QOS POLICY ID,

DDS DATAREADERRESOURCELIMITS QOS POLICY ID,

DDS DATAWRITERRESOURCELIMITS QOS POLICY ID,

DDS DATAREADERPROTOCOL QOS POLICY ID,

DDS DATAWRITERPROTOCOL QOS POLICY ID,

DDS DOMAINPARTICIPANTRESOURCELIMITS QOS -

POLICY ID,

DDS EVENT QOS POLICY ID,

DDS DATABASE QOS POLICY ID,

DDS RECEIVERPOOL QOS POLICY ID,

DDS DISCOVERYCONFIG QOS POLICY ID,

DDS EXCLUSIVEAREA QOS POLICY ID ,

DDS SYSTEMRESOURCELIMITS QOS POLICY ID,

DDS TRANSPORTSELECTION QOS POLICY ID,

DDS TRANSPORTUNICAST QOS POLICY ID,

DDS TRANSPORTMULTICAST QOS POLICY ID,

DDS TRANSPORTBUILTIN QOS POLICY ID,

DDS TYPESUPPORT QOS POLICY ID,

DDS PROPERTY QOS POLICY ID,

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

338 Module Documentation

DDS PUBLISHMODE QOS POLICY ID,

DDS ASYNCHRONOUSPUBLISHER QOS POLICY ID,

DDS ENTITYNAME QOS POLICY ID ,

DDS BATCH QOS POLICY ID,

DDS PROFILE QOS POLICY ID,

DDS LOCATORFILTER QOS POLICY ID,

DDS MULTICHANNEL QOS POLICY ID ,

DDS AVAILABILITY QOS POLICY ID,

DDS TRANSPORTMULTICASTMAPPING QOS POLICY -

ID = 1036,

DDS LOGGING QOS POLICY ID }

Type to identify QosPolicies.

5.84.1 Detailed Description

Quality of Service (QoS) policies.

Data Distribution Service (DDS) relies on the use of QoS. A QoS is a set of

characteristics that controls some aspect of the behavior of DDS. A QoS is

comprised of individual QoS policies (objects conceptually deriving from an

abstract QosPolicy class).

The QosPolicy provides the basic me chanism for an application to specify quality

of service parameters. It has an attribute name that is used to uniquely identify

each QosPolicy.

QosPolicy implementation is comprised of a name, an ID, and a type. The type

of a QosPolicy value may be atomic, such as an integer or ﬂoat, or compound

(a structure). Compound types are used whenever multiple parameters must

be set coherently to deﬁne a consistent value for a QosPolicy.

QoS (i.e., a list of QosPolicy objects) may be associated with all DDSEntity

(p. 1253) objects in the system such as DDSTopic (p. 1419), DDSDataWriter

(p. 1113), DDSDataReader (p. 1087), DDSPublisher (p. 1346), DDSSub-

scriber (p. 1390), and DDSDomainParticipant (p. 1139).

5.84.2 Specifying QoS on entities

QosPolicies can be set programmatically when an DDSEntity (p. 1253) is c re-

ated, or modiﬁed with the DDSEntity (p. 1253)’s set qos (abstract) (p. 1254)

method.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.84 QoS Poli cies 339

QosPolicies can also be conﬁgured from XML resources (ﬁles, strings). With

this approach, you can change the QoS without recompiling the application.

For more information, see Conﬁguring QoS Proﬁles with XML (p. 151).

To customize a DDSEntity (p. 1253)’s QoS before creating the entity, the cor-

rect pattern is:

First, initialize a QoS object with the appropriate INITIALIZER con-

structor.

Call the relevant get <entity> default qos() method.

Modify the QoS values as desired.

Finally, create the e ntity.

Each QosPolicy is treated independently from the others. This approach has

the advantage of being very extensible. However, there may be cases where

several policies are in conﬂict. Consistency checking is performed each time the

policies are modiﬁed via the set qos (abstract) (p. 1254) operation, or when

the DDSEnti ty (p. 1253) is created.

When a policy is changed after being set to a given value, it is not required that

the new value be applied instantaneously; RTI Connext is allowed to apply it af-

ter a transition phase. In addition, some QosPolicy have immutable s em antics,

meaning that they can only be speciﬁed either at DDSEntity (p. 1253) creation

time or else prior to calling the DDSEntity::enable (p. 1256) operation on the

entity.

Each DDSEntity (p. 1253) can be conﬁgured with a list of QosPolicy ob-

jects. However, not all QosPolicies are supported by each DDSEntity (p. 1253).

For instance, a DDSDomainParticipant (p. 1139) supports a diﬀerent set of

QosPolicies than a DDSTopic (p. 1419) or a DDSPublisher (p. 1346).

5.84.3 QoS compatibility

In several cases, for communications to oc cur properly (or eﬃciently), a QosPol-

icy on the publisher side must be compatible with a corresponding policy on

the subscriber side. For example, if a DDSSubscriber (p. 1390) requests to

receive data reliably while the corresponding DDSPublisher (p. 1346) deﬁnes

a best-eﬀort policy, communication will not happen as requested.

To address this issue and maintain the desirable decoupling of publication

and subscription as much as possible, the QosPolicy speciﬁcation follows the

subscriber-requested, publisher-oﬀered pattern.

In this pattern, the subscriber side can specify a ”requested” value for a par-

ticular QosPolicy. The publisher side specifes an ”oﬀered” value for that

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

340 Module Documentation

QosPolicy. RTI Connext will then determine whether the value requested

by the subscriber side is compatible with what is oﬀered by the publisher

side. If the two policie s are compatible, then communication will be estab-

lished. If the two policies are not compatible, RTI Connext will not e stab-

lish communications between the two DDSEntity (p. 1253) objects and will

record this fact by means of the DDS OFFERED INCOMPATIBLE -

QOS STATUS (p. 323) on the publisher end and DDS REQUESTED -

INCOMPATIBLE QOS STATUS (p. 323) on the subscriber end. The ap-

plication can detect this fact by means of a DDSListener (p. 1318) or a

DDSCondition (p. 1075).

The following properties are deﬁned on a QosPolicy.

RxO (p. 340) property

The QosPolicy objects that need to b e se t in a compatible manner between

the publisher and subscriber end are indicated by the setting of the

RxO (p. 340) property:

– RxO (p. 340) = YES indicates that the policy can be set both at

the publishing and subscribing ends and the values must be set in a

compatible manner. In this case the compatible values are explicitly

deﬁned.

– RxO (p. 340) = NO indicates that the policy can be set both at the

publishing and subscribing ends but the two settings are independent.

That is, all combinations of values are compatible.

– RxO (p. 340) = N/A indicates that the policy can only be speciﬁed

at either the publishing or the subscribing end, but not at both ends.

So compatibility does not apply.

Changeable (p. 340) property

Determines whether a QosPolicy can be changed.

NO (p. 340) – policy can only b e speciﬁed at DDSEntity (p. 1253)

creation time.

UNTIL ENABLE (p. 340) – policy can only be changed b efore the

DDSEntity (p. 1253) is enabled.

YES (p. 340) – policy can be changed at any time.

5.84.4 Deﬁne Documentation

5.84.4.1 #deﬁne DDS QOS POLICY COUNT

Number of QoS policies in DDS QosPolicyId t (p. 341).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.84 QoS Poli cies 341

5.84.5 Enumeration Type Documentation

5.84.5.1 enum DDS QosPolicyId t

Type to identify QosPolicies.

Enumerator:

DDS INVALID QOS POLICY ID Identiﬁer for an invalid QoS pol-

icy.

DDS USERDATA QOS POLICY ID Identiﬁer for DDS -

UserDataQosPolicy (p. 1048).

DDS DURABILITY QOS POLICY ID Identiﬁer for DDS -

DurabilityQosPolicy (p. 614).

DDS PRESENTATION QOS POLICY ID Identiﬁer for DDS -

PresentationQosPolicy (p. 823).

DDS DEADLINE QOS POLICY ID Identiﬁer for DDS -

DeadlineQosPolicy (p. 567).

DDS LATENCYBUDGET QOS POLICY ID Identiﬁer for

DDS LatencyBudgetQosPolicy (p. 771).

DDS OWNERSHIP QOS POLICY ID Identiﬁer for DDS -

OwnershipQosPolicy (p. 807).

DDS OWNERSHIPSTRENGTH QOS POLICY ID Identiﬁer for

DDS OwnershipStrengthQosPolicy (p. 814).

DDS LIVELINESS QOS POLICY ID Identiﬁer for DDS -

LivelinessQosPolicy (p. 779).

DDS TIMEBASEDFILTER QOS POLICY ID Identiﬁer for

DDS TimeBasedFilterQosPolicy (p. 954).

DDS PARTITION QOS POLICY ID Identiﬁer for DDS -

PartitionQosPolicy (p. 820).

DDS RELIABILITY QOS POLICY ID Identiﬁer for DDS -

ReliabilityQosPolicy (p. 865).

DDS DESTINATIONORDER QOS POLICY ID Identiﬁer for

DDS DestinationOrderQosPolicy (p. 570).

DDS HISTORY QOS POLICY ID Identiﬁer for DDS -

HistoryQosPolicy (p. 758).

DDS RESOURCELIMITS QOS POLICY ID Identiﬁer for

DDS ResourceLimitsQosPolicy (p. 879).

DDS ENTITYFACTORY QOS POLICY ID Identiﬁer for DDS -

EntityFactoryQosPolicy (p. 733).

DDS WRITERDATALIFECYCLE QOS POLICY ID Identiﬁer

for DDS WriterDataLifecycleQosPolicy (p. 1071).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

342 Module Documentation

DDS READERDATALIFECYCLE QOS POLICY ID Identiﬁer

for DDS ReaderDataLifecycleQosPolicy (p. 859).

DDS TOPICDATA QOS POLICY ID Identiﬁer for DDS -

TopicDataQosPolicy (p. 963).

DDS GROUPDATA QOS POLICY ID Identiﬁer for DDS -

GroupDataQosPolicy (p. 755).

DDS TRANSPORTPRIORITY QOS POLICY ID Identiﬁer for

DDS TransportPriorityQosPolicy (p. 983).

DDS LIFESPAN QOS POLICY ID Identiﬁer for DDS -

LifespanQosPolicy (p. 773).

DDS DURABILITYSERVICE QOS POLICY ID Identiﬁer for

DDS DurabilityServiceQosPolicy (p. 618).

DDS TYPE CONSISTENCY ENFORCEMENT QOS POLICY ID

Identiﬁer for DDS TypeConsistencyEnforcementQosPolicy

(p. 1038).

DDS WIREPROTOCOL QOS POLICY ID <<eXtension>>

( p. 199) Identiﬁer for DDS WireProtocolQosPolicy (p. 1059)

DDS DISCOVERY QOS POLICY ID <<eXtension>> ( p. 199)

Identiﬁer for DDS DiscoveryQosPolicy (p. 582)

DDS DATAREADERRESOURCELIMITS QOS POLICY ID

<<eXtension>> ( p. 199) Identiﬁer for DDS -

DataReaderResourceLimitsQosPolicy (p. 521)

DDS DATAWRITERRESOURCELIMITS QOS POLICY ID

<<eXtension>> ( p. 199) Identiﬁer for DDS -

DataWriterResourceLimitsQosPolicy (p. 560)

DDS DATAREADERPROTOCOL QOS POLICY ID

<<eXtension>> ( p. 199) Identiﬁer for DDS -

DataReaderProtocolQosPolicy (p. 501)

DDS DATAWRITERPROTOCOL QOS POLICY ID

<<eXtension>> ( p. 199) Identiﬁer for DDS -

DataWriterProtocolQosPolicy (p. 535)

DDS DOMAINPARTICIPANTRESOURCELIMITS QOS POLICY ID

<<eXtension>> ( p. 199) Identiﬁer for DDS -

DomainParticipantResourceLimitsQosPolicy (p. 593)

DDS EVENT QOS POLICY ID <<eXtension>> ( p. 199) Identi-

ﬁer for DDS Eve ntQosPolicy (p. 739)

DDS DATABASE QOS POLICY ID <<eXtension>> ( p. 199)

Identiﬁer for DDS DatabaseQosPol icy (p. 495)

DDS RECEIVERPOOL QOS POLICY ID <<eXtension>>

( p. 199) Identiﬁer for DDS ReceiverPoolQosPolicy (p. 862)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.84 QoS Poli cies 343

DDS DISCOVERYCONFIG QOS POLICY ID

<<eXtension>> ( p. 199) Identiﬁer for DDS -

DiscoveryConﬁgQosPolicy (p. 573)

DDS EXCLUSIVEAREA QOS POLICY ID <<eXtension>>

( p. 199) Identiﬁer for DDS ExclusiveAreaQosPolicy (p. 742)

DDS SYSTEMRESOURCELIMITS QOS POLICY ID

<<eXtension>> ( p. 199) Identiﬁer for DDS -

SystemResourceLimitsQosPolicy (p. 948)

DDS TRANSPORTSELECTION QOS POLICY ID

<<eXtension>> ( p. 199) Identiﬁer for DDS -

TransportSelectionQosPol icy (p. 985)

DDS TRANSPORTUNICAST QOS POLICY ID

<<eXtension>> ( p. 199) Identiﬁer for DDS -

TransportUnicastQosPolicy (p. 987)

DDS TRANSPORTMULTICAST QOS POLICY ID

<<eXtension>> ( p. 199) Identiﬁer for DDS -

TransportMulticastQosPoli cy (p. 978)

DDS TRANSPORTBUILTIN QOS POLICY ID

<<eXtension>> ( p. 199) Identiﬁer for DDS -

TransportBuiltinQosPolicy (p. 969)

DDS TYPESUPPORT QOS POLICY ID <<eXtension>>

( p. 199) Identiﬁer for DDS TypeSupportQosPolicy (p. 1040)

DDS PROPERTY QOS POLICY ID <<eXtension>> ( p. 199)

Identiﬁer for DDS PropertyQosPolicy (p. 834)

DDS PUBLISHMODE QOS POLICY ID <<eXtension>>

( p. 199) Identiﬁer for DDS PublishModeQosPolicy (p. 853)

DDS ASYNCHRONOUSPUBLISHER QOS POLICY ID

<<eXtension>> ( p. 199) Identiﬁer for DDS -

AsynchronousPublisherQosPolicy (p. 466)

DDS ENTITYNAME QOS POLICY ID <<eXtension>>

( p. 199) Identiﬁer for DDS EntityNameQosPolicy (p. 735)

DDS BATCH QOS POLICY ID <<eXtension>> ( p. 199) Identi-

ﬁer for DDS BatchQosPolicy (p. 476)

DDS PROFILE QOS POLICY ID <<eXtension>> ( p. 199)

Identiﬁer for DDS ProﬁleQosPolic y (p. 830)

DDS LOCATORFILTER QOS POLICY ID <<eXtension>>

( p. 199) Identiﬁer for DDS LocatorFilterQosPolicy (p. 787)

DDS MULTICHANNEL QOS POLICY ID <<eXtension>>

( p. 199) Identiﬁer for DDS MultiChannelQosPolicy (p. 796)

DDS AVAILABILITY QOS POLICY ID <<eXtension>>

( p. 199) Identiﬁer for DDS AvailabilityQosPolicy (p. 471)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

344 Module Documentation

DDS TRANSPORTMULTICASTMAPPING QOS POLICY ID

DDS LOGGING QOS POLICY ID <<eXtension>> ( p. 199)

Identiﬁer for DDS LoggingQosPol icy (p. 791)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.85 USER DATA 345

5.85 USER DATA

Attaches a buﬀer of opaque data that is distributed by means of Built-in

Topics (p. 42) during discovery.

Classes

struct DDS UserDataQosPolicy

Attaches a buﬀer of opaque data that is distributed by means of Built-in

Topics ( p. 42) during discovery.

Variables

const char ∗const DDS USERDATA QOS POLICY NAME

Stringiﬁed human-readable name for DDS UserDataQosPolicy ( p. 1048).

5.85.1 Detailed Description

Attaches a buﬀer of opaque data that is distributed by means of Built-in

Topics (p. 42) during discovery.

5.85.2 Variable Documentation

5.85.2.1 const char∗ const DDS USERDATA QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS UserDataQosPolicy (p. 1048).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

346 Module Documentation

5.86 TOPIC DATA

Attaches a buﬀer of opaque data that is distributed by means of Built-in

Topics (p. 42) during discovery.

Classes

struct DDS TopicDataQosPolicy

Attaches a buﬀer of opaque data that is distributed by means of Built-in

Topics ( p. 42) during discovery.

Variables

const char ∗const DDS TOPICDATA QOS POLICY NAME

Stringiﬁed human-readable name for DDS TopicDataQosPolicy ( p. 963).

5.86.1 Detailed Description

Attaches a buﬀer of opaque data that is distributed by means of Built-in

Topics (p. 42) during discovery.

5.86.2 Variable Documentation

5.86.2.1 const char∗ const DDS TOPICDATA QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS TopicDataQosPolicy (p. 963).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.87 GROUP DATA 347

5.87 GROUP DATA

Attaches a buﬀer of opaque data that is distributed by means of Built-in

Topics (p. 42) during discovery.

Classes

struct DDS GroupDataQosPolicy

Attaches a buﬀer of opaque data that is distributed by means of Built-in

Topics ( p. 42) during discovery.

Variables

const char ∗const DDS GROUPDATA QOS POLICY NAME

Stringiﬁed human-readable name for DDS GroupDataQosPolicy ( p. 755).

5.87.1 Detailed Description

Attaches a buﬀer of opaque data that is distributed by means of Built-in

Topics (p. 42) during discovery.

5.87.2 Variable Documentation

5.87.2.1 const char∗ const DDS GROUPDATA QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS GroupDataQosPolicy (p. 755).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

348 Module Documentation

5.88 DURABILITY

This QoS policy speciﬁes whether or not RTI Connext will store and deliver

previously published data samples to new DDSDataReader (p. 1087) entities

that join the network later.

Classes

struct DDS DurabilityQosPolicy

This QoS policy speciﬁes whether or not RTI Connext will store and de-

liver previously published data samples to new DDSDataReader ( p. 1087)

entities that join the network later.

Enumerations

enum DDS DurabilityQosPolicyKind {

DDS VOLATILE DURABILITY QOS,

DDS TRANSIENT LOCAL DURABILITY QOS,

DDS TRANSIENT DURABILITY QOS,

DDS PERSISTENT DURABILITY QOS }

Kinds of durability.

Variables

const char ∗const DDS DURABILITY QOS POLICY NAME

Stringiﬁed human-readable name for DDS DurabilityQosPolicy ( p. 614).

5.88.1 Detailed Description

This QoS policy speciﬁes whether or not RTI Connext will store and deliver

previously published data samples to new DDSDataReader (p. 1087) entities

that join the network later.

5.88.2 Enumeration Type Documentation

5.88.2.1 enum DDS DurabilityQosPolicyKi nd

Kinds of durability.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.88 DURABILITY 349

QoS:

DDS DurabilityQosPolicy (p. 614)

Enumerator:

DDS VOLATILE DURABILITY QOS [default] RTI Connext

does not need to keep any samples of data instances on behalf of

any DDSDataReader (p. 1087) that is unknown by the DDS-

DataWriter (p. 1113) at the time the instance is written.

In other words, RTI Connext will only attempt to provide the data to

existing subscribers.

This option does not require RTI Persistence Service.

DDS TRANSIENT LOCAL DURABILITY QOS RTI Connext

will attempt to keep some samples s o that they can be delivered to

any potential late-joining DDSDataReader (p. 1087).

Which particular samples are kept depends on other QoS

such as DDS HistoryQosPolicy (p. 758) and DDS -

ResourceLimitsQosPolicy (p. 879). RTI Connext is only required

to keep the data in memory of the DDSDataWriter (p. 1113) that

wrote the data.

Data is not required to survive the DDSDataWriter (p. 1113).

For this setting to be eﬀective, you must also set the

DDS ReliabilityQosPolicy::kind (p. 868) to DDS RELIABLE -

RELIABILITY QOS (p. 363).

This option does not require RTI Persistence Service.

DDS TRANSIENT DURABILITY QOS RTI Connext will at-

tempt to keep some samples so that they can be delivered to any

potential late-joining DDSDataReader (p. 1087).

Which particular samples are kept depends on other QoS

such as DDS HistoryQosPolicy (p. 758) and DDS -

ResourceLimitsQosPolicy (p. 879). RTI Connext is only required

to keep the data in memory and not in permanent storage.

Data is not tied to the lifecycle of the DDSDataWriter (p. 1113).

Data will survive the DDSDataWriter (p. 1113).

This option requires RTI Persistence Service.

DDS PERSISTENT DURABILITY QOS Data is kept on perma-

nent storage, so that they can outlive a system session.

This option requires RTI Persistence Service.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

350 Module Documentation

5.88.3 Variable Documentation

5.88.3.1 const char∗ const DDS DURABILITY QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS Durabili tyQosPolicy (p. 614).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.89 PRESENTATION 351

5.89 PRESENTATION

Speciﬁes how the samples representing changes to data instances are presented

to a subscribing application.

Classes

struct DDS PresentationQosPolicy

Speciﬁes how the samples representing changes to data instances are pre-

sented to a subscribing application.

Enumerations

enum DDS PresentationQosPolicyAccessScopeKind {

DDS INSTANCE PR ESENTATION QOS,

DDS TOPIC PRESENTATION QOS,

DDS GROUP PR ESENTATION QOS,

DDS HIGHEST OFFERED PRESENTATION QOS }

Kinds of presentation ”access scope”.

Variables

const char ∗const DDS PRESENTATION QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS PresentationQosPolicy

( p. 823).

5.89.1 Detailed Description

Speciﬁes how the samples representing changes to data instances are presented

to a subscribing application.

5.89.2 Enumeration Type Documentation

5.89.2.1 enum DDS PresentationQosPolicyA ccessScopeKind

Kinds of presentation ”access scope”.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

352 Module Documentation

Access scope determines the largest scope spanning the e ntities for which the

order and coherency of changes can be preserved.

QoS:

DDS PresentationQosPolicy (p. 823)

Enumerator:

DDS INSTANCE PRESENTATION QOS [default] Scope spans

only a single instance.

Indicates that changes to one instance need not be coherent nor or-

dered with respect to changes to any other instance. In other words,

order and coherent changes apply to each instance separately.

DDS TOPIC PRESENTATION QOS Scope spans to all instances

within the same DDSDataWriter (p. 1113) (or DDSDataReader

(p. 1087)), but not across instances in diﬀerent DDSDataWriter

(p. 1113) (or DDSDataReader (p. 1087)).

DDS GROUP PRESENTATION QOS Scope spans to all instances

belonging to DDSDataWriter (p. 1113) (or DDSDataReader

(p. 1087)) entities within the same DDSPublisher (p. 1346) (or

DDSSubscriber (p. 1390)).

DDS HIGHEST OFFERED PRESENTATION QOS This value

only applies to a DDSSubscriber (p. 1390). The DDSSubscriber

(p. 1390) will use the access scope speciﬁed by each remote DDSPub-

lisher (p. 1346).

5.89.3 Variable Documentation

5.89.3.1 const char∗ const DDS PRESENTATION QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS PresentationQosPolicy (p. 823).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.90 DEADLINE 353

5.90 DEADLINE

Expresses the maximum duration (deadline) within which an instance is ex-

pected to be updated.

Classes

struct DDS DeadlineQosPolicy

Expresses the maximum duration (deadline) within which an instance is ex-

pected to be updated.

Variables

const char ∗const DDS DEADLINE QOS POLICY NAME

Stringiﬁed human-readable name for DDS DeadlineQosPolicy ( p. 567).

5.90.1 Detailed Description

Expresses the maximum duration (deadline) within which an instance is ex-

pected to be updated.

5.90.2 Variable Documentation

5.90.2.1 const char∗ const DDS DEADLINE QOS POLICY NAME

Stringiﬁed human-readable name for DDS Deadli neQosPolicy (p. 567).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

354 Module Documentation

5.91 LATE NCY BUDGET

Provides a hint as to the maximum acceptable delay from the time the data is

written to the time it is received by the subscribing applications.

Classes

struct DDS LatencyBudgetQosPolicy

Provides a hint as to the maximum acceptable delay from the time the data

is written to the time it is received by the subscribing applications.

Variables

const char ∗const DDS LATENCYBUDGET QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS LatencyBudgetQosPolicy

( p. 771).

5.91.1 Detailed Description

Provides a hint as to the maximum acceptable delay from the time the data is

written to the time it is received by the subscribing applications.

5.91.2 Variable Documentation

5.91.2.1 const char∗ const DDS LATENCYBUDGET QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS LatencyBudgetQosPol icy

(p. 771).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.92 OWNERSHIP 355

5.92 OWNERSHIP

Speciﬁes whether it is allowed for multiple DDSDataWriter (p. 1113) (s) to

write the same instance of the data and if so, how these modiﬁcations should

be arbitrated.

Classes

struct DDS OwnershipQosPolicy

Speciﬁes whether it is allowed for multiple DDSDataWriter ( p. 1113) (s)

to write the same instance of the data and if so, how these modiﬁcations

should be arbitrated.

Enumerations

enum DDS OwnershipQosPolicyKind {

DDS SHARED OWNERSHIP QOS,

DDS EXCLUSIVE OWNERSHIP QOS }

Kinds of ownership.

Variables

const char ∗const DDS OWNERSHIP QOS POLICY NAME

Stringiﬁed human-readable name for DDS OwnershipQosPolicy ( p. 807).

5.92.1 Detailed Description

Speciﬁes whether it is allowed for multiple DDSDataWriter (p. 1113) (s) to

write the same instance of the data and if so, how these modiﬁcations should

be arbitrated.

5.92.2 Enumeration Type Documentation

5.92.2.1 enum DDS OwnershipQosPolicyKind

Kinds of ownership.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

356 Module Documentation

QoS:

DDS OwnershipQosPolicy (p. 807)

Enumerator:

DDS SHARED OWNERSHIP QOS [default] Indicates shared

ownership for each instance.

Multiple writers are allowed to update the same instance and all the

updates are made available to the readers. In other words there is no

concept of an owner for the instances.

This is the default behavior if the OWNERSHIP (p. 355) policy is

not speciﬁed or supported.

DDS EXCLUSIVE OWNERSHIP QOS Indicates each instance

can only be owned by one DDSDataWriter (p. 1113), but the owner

of an instance can change dynamically.

The selection of the owner is controlled by the setting of the OWN-

ERSHIP STRENGTH (p. 357) policy. The owner is always set to

be the highest-strength DDSDataWriter (p. 1113) object among the

ones currently active (as determined by the LIVELINESS (p. 358)).

5.92.3 Variable Documentation

5.92.3.1 const char∗ const DDS OWNERSHIP QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS OwnershipQosPolicy (p. 807).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.93 OWNERSHIP STRENGTH 357

5.93 OWNERSHIP STRENGTH

Speciﬁes the value of the strength used to arbitrate among multiple DDS-

DataWriter (p. 1113) objects that attempt to modify the same instance of a

data type (identiﬁed by DDSTopic (p. 1419) + key).

Classes

struct DDS OwnershipStrengthQosPolicy

Speciﬁes the value of the strength used to arbitrate among multiple DDS-

DataWriter ( p. 1113) objects that attempt to modify the same instance of

a data type (identiﬁed by DDSTopic ( p. 1419) + key).

Variables

const char ∗const DDS OWNERSHIPSTRENGTH QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS OwnershipStrengthQosPolicy

( p. 814).

5.93.1 Detailed Description

Speciﬁes the value of the strength used to arbitrate among multiple DDS-

DataWriter (p. 1113) objects that attempt to modify the same instance of a

data type (identiﬁed by DDSTopic (p. 1419) + key).

5.93.2 Variable Documentation

5.93.2.1 const char∗ const DDS OWNERSHIPSTRENGTH QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS OwnershipStrengthQosPolicy

(p. 814).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

358 Module Documentation

5.94 LIVELINESS

Speciﬁes and conﬁgures the mechanism that allows DDSDataReader (p. 1087)

entities to detect when DDSDataWriter (p. 1113) entities become discon-

nected or ”dead.”.

Classes

struct DDS LivelinessQosPolicy

Speciﬁes and conﬁgures the mec hanism that allows DDSDataReader

( p. 1087) entities to detect when DDSDataWriter ( p. 1113) entities be-

come disconnected or ”dead.”.

Enumerations

enum DDS LivelinessQosPolicyKind {

DDS AUTOMATIC LIVELINESS QOS,

DDS MANUAL BY PARTICIPANT LIVELINESS QOS,

DDS MANUAL BY TOPIC LIVELINESS QOS }

Kinds of liveliness.

Variables

const char ∗const DDS LIVELINESS QOS POLICY NAME

Stringiﬁed human-readable name for DDS LivelinessQosPolicy ( p. 779).

5.94.1 Detailed Description

Speciﬁes and conﬁgures the mechanism that allows DDSDataReader (p. 1087)

entities to detect when DDSDataWriter (p. 1113) entities become discon-

nected or ”dead.”.

5.94.2 Enumeration Type Documentation

5.94.2.1 enum DDS LivelinessQosPolicyKind

Kinds of liveliness.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.94 LIVELINESS 359

QoS:

DDS LivelinessQosPolicy (p. 779)

Enumerator:

DDS AUTOMATIC LIVELINESS QOS [default] The infrastruc-

ture will automatically signal liveliness for the DDSDataWriter

(p. 1113) (s) at least as often as required by the lease duration.

A DDSDataWriter (p. 1113) with this setting does not need to

take any spec iﬁc action in order to be considered ’alive.’ The DDS-

DataWriter (p. 1113) is only ’not alive’ when the participant to which

it belongs terminates (gracefully or not), or when there is a network

problem that prevents the current participant from contacting that

remote participant.

DDS MANUAL BY PARTICIPANT LIVELINESS QOS RTI

Connext will ass ume that as long as at least one DDSDataWriter

(p. 1113) belonging to the DDSDomainParticipant (p. 1139) (or

the DDSDomainParticipant (p. 1139) itself) has asserted its

liveliness, then the other Entities b elonging to that same DDSDo-

mainParticipant (p. 1139) are also alive.

The user application takes responsibility to signal liveliness to

RTI Connext either by calling DDSDomainParticipant::assert -

liveliness (p. 1192), or by calling DDSDataWriter::assert -

liveliness (p. 1121), or FooDataWriter::write (p. 1484) on any

DDSDataWriter (p. 1113) belonging to the DDSDomainPartic-

ipant (p. 1139).

DDS MANUAL BY TOPIC LIVELINESS QOS RTI Connext

will only assume liveliness of the DDSDataWriter (p. 1113) if the

application has asserted liveliness of that DDSDataWriter (p. 1113)

itself.

The user application takes re sponsibility to signal liveliness to RTI

Connext using the DDSDataWriter::assert liveliness (p. 1121)

method, or by writing some data.

5.94.3 Variable Documentation

5.94.3.1 const char∗ const DDS LIVELINESS QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS LivelinessQosPolicy (p. 779).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

360 Module Documentation

5.95 TIME BASED FILTER

Filter that allows a DDSDataReader (p. 1087) to specify that it is interested

only in (potentially) a subset of the values of the data.

Classes

struct DDS TimeBasedFilterQosPolicy

Filter that allows a DDSDataReader ( p. 1087) to specify that it is inter-

ested only in (potentially) a subset of the values of the data.

Variables

const char ∗const DDS TIMEBASEDFILTER QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS TimeBasedFilterQosPolicy

( p. 954).

5.95.1 Detailed Description

Filter that allows a DDSDataReader (p. 1087) to specify that it is interested

only in (potentially) a subset of the values of the data.

5.95.2 Variable Documentation

5.95.2.1 const char∗ const DDS TIMEBASEDFILTER QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS TimeBasedFilterQosPolicy

(p. 954).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.96 PARTITION 361

5.96 PARTITION

Set of strings that introduces a logical partition among the topics visible by a

DDSPublisher (p. 1346) and a DDSSubscriber (p. 1390).

Classes

struct DDS PartitionQosPolicy

Set of strings that introduces a logical partition among the topics visible by

a DDSPublisher ( p. 1346) and a DDSSubscriber ( p. 1390).

Variables

const char ∗const DDS PARTITION QOS POLICY NAME

Stringiﬁed human-readable name for DDS PartitionQosPolicy ( p. 820).

5.96.1 Detailed Description

Set of strings that introduces a logical partition among the topics visible by a

DDSPublisher (p. 1346) and a DDSSubscriber (p. 1390).

5.96.2 Variable Documentation

5.96.2.1 const char∗ const DDS PARTITION QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS PartitionQosPolicy (p. 820).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

362 Module Documentation

5.97 RELIABILITY

Indicates the level of reliability oﬀered/requested by RTI Connext.

Classes

struct DDS ReliabilityQosPolicy

Indicates the level of reliability oﬀered/requested by RTI Connext.

Enumerations

enum DDS ReliabilityQosPolicyKind {

DDS BEST EFFORT RELIABILITY QOS,

DDS RELIABLE RELIABILITY QOS }

Kinds of reliability.

enum DDS ReliabilityQosPolicyAcknowledgmentModeKind {

DDS PROTOCOL ACKNOWLEDGMENT MODE,

DDS APPLICATION AUTO ACKNOWLEDGMENT MODE ,

DDS APPLICATION EXPLICIT ACKNOWLEDGMENT -

MODE }

Kinds of acknowledgment.

Variables

const char ∗const DDS RELIABILITY QOS POLICY NAME

Stringiﬁed human-readable name for DDS ReliabilityQosPolicy ( p. 865).

5.97.1 Detailed Description

Indicates the level of reliability oﬀered/requested by RTI Connext.

5.97.2 Enumeration Type Documentation

5.97.2.1 enum DDS ReliabilityQosPolicyKind

Kinds of reliability.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.97 RELIABILITY 363

QoS:

DDS ReliabilityQosPolicy (p. 865)

Enumerator:

DDS BEST EFFORT RELIABILITY QOS Indicates that it is ac-

ceptable to not retry propagation of any samples.

Presumably new values for the samples are generated often enough

that it is not necessary to re-send or acknowledge any samples.

[default] for DDSDataReader (p. 1087) and DDSTopic (p. 1419)

DDS RELIABLE RELIABILITY QOS Speciﬁes RTI Connext will

attempt to deliver all samples in its history. Missed samples may be

retried.

In steady-state (no modiﬁcations communicated via the DDS-

DataWriter (p. 1113)), RTI Connext guarantees that all samples in

the DDSDataWriter (p. 1113) history will eventually be delivered to

all the DDSDataReader (p. 1087) objects (subject to timeouts that

indicate loss of communication with a particular DDSSubscriber

(p. 1390)).

Outside steady state, the HISTORY (p. 367) and RESOURCE -

LIMITS (p. 371) policies will determine how samples become part of

the history and whether samples can be discarded from it.

[default] for DDSDataWriter (p. 1113)

5.97.2.2 enum DDS -

ReliabilityQosPolicyAcknowledgmentModeKind

Kinds of acknowledgment.

QoS:

DDS ReliabilityQosPolicy (p. 865)

Enumerator:

DDS PROTOCOL ACKNOWLEDGMENT MODE Samples are

acknowledged by RTPS protocol.

Samples are acknowledged according to the Real-Time Publish-

Subscrib e (RTPS) interoperability protocol.

DDS APPLICATION AUTO ACKNOWLEDGMENT MODE

Samples are acknowleged automatically after a subscribing application

has accessed them.

A sample received by a FooDataReader (p. 1444) is acknowl-

edged after it has b e en taken and then returned. Speciﬁcally,

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

364 Module Documentation

all samples taken by a call to FooDataReader::take (p. 1448)

are acknowledged after Fo oDataReader:: return loan (p. 1471) is

called. Acknowledgments are sent at a rate determinded by DDS -

RtpsReliableReaderProtocol t::samples per app ack (p. 887).

DDS APPLICATION EXPLICIT ACKNOWLEDGMENT MODE

Samples are acknowledged after the subscribing application explicitly

calls acknowledge on the samples.

Samples received by a DDSDataReader (p. 1087) are explic-

itly acknowledged by the subscribing application, after it calls

either DDSDataReader::acknowledge all (p. 1095) or DDS-

DataReader::acknowledge sample (p. 1095).

5.97.3 Variable Documentation

5.97.3.1 const char∗ const DDS RELIABILITY QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS Re liabi li tyQosPolicy (p. 865).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.98 DESTINATION ORDER 365

5.98 DESTINATION ORDER

Controls the criteria used to determine the logical order among changes made by

DDSPublisher (p. 1346) entities to the same instance of data (i.e., matching

DDSTopic (p. 1419) and key).

Classes

struct DDS DestinationOrderQosPolicy

Controls how the middleware will deal with data sent by multiple DDS-

DataWriter ( p. 1113) entities for the same instance of data (i.e., same

DDSTopic ( p. 1419) and key).

Enumerations

enum DDS DestinationOrderQosPolicyKind {

DDS BY RECEPTION TIMESTAMP -

DESTINATIONORDER QOS,

DDS BY SOURCE TIMESTAMP DESTINATIONORDER -

QOS }

Kinds of destination order.

Variables

const char ∗const DDS DESTINATIONORDER QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS DestinationOrderQosPolicy

( p. 570).

5.98.1 Detailed Description

Controls the criteria used to determine the logical order among changes made by

DDSPublisher (p. 1346) entities to the same instance of data (i.e., matching

DDSTopic (p. 1419) and key).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

366 Module Documentation

5.98.2 Enumeration Type Documentation

5.98.2.1 enum DDS DestinationOrderQosPolicyKind

Kinds of destination order.

QoS:

DDS DestinationOrderQosPolicy (p. 570)

Enumerator:

DDS BY RECEPTION TIMESTAMP DESTINATIONORDER QOS

[default] Indicates that data is ordered based on the reception time

at each DDSSubscriber (p. 1390).

Since each subscriber may receive the data at diﬀerent times there is

no guaranteed that the changes will be seen in the same order. Con-

sequently, it is possible for each subscriber to end up with a diﬀerent

ﬁnal value for the data.

DDS BY SOURCE TIMESTAMP DESTINATIONORDER QOS

Indicates that data is ordered based on a time-stamp placed at the

source (by RTI Connext or by the application).

In any case this guarantees a consistent ﬁnal value for the data in all

subscribers.

See also:

Special Instructions if Using ’Timestamp’ APIs and BY -

SOURCE TIMESTAMP Destination Ordering: (p. 1358)

5.98.3 Variable Documentation

5.98.3.1 const char∗ const DDS DESTINATIONORDER QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS DestinationOrderQosPoli cy

(p. 570).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.99 HISTORY 367

5.99 HISTORY

Speciﬁes the be havior of RTI Connext in the case where the value of an instance

changes (one or more times) before it can be successfully communicated to one

or more existing subscribers.

Classes

struct DDS HistoryQosPolicy

Speciﬁes the behavior of RTI Connext in the case where the value of a sample

changes (one or more times) before it can be successfully communicated to

one or more existing subscribers.

Enumerations

enum DDS HistoryQosPolicyKind {

DDS KEEP LAST HISTORY QOS,

DDS KEEP ALL HISTORY QOS }

Kinds of history.

enum DDS ReﬁlterQosPolicyKind {

DDS NONE REFILTER QOS,

DDS ALL REFILTER QOS,

DDS ON DEMAND REFILTER QOS }

<<eXtension>> (p. 199) Kinds of Reﬁltering

Variables

const char ∗const DDS HISTORY QOS POLICY NAME

Stringiﬁed human-readable name for DDS HistoryQosPolicy ( p. 758).

5.99.1 Detailed Description

Speciﬁes the be havior of RTI Connext in the case where the value of an instance

changes (one or more times) before it can be successfully communicated to one

or more existing subscribers.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

368 Module Documentation

5.99.2 Enumeration Type Documentation

5.99.2.1 enum DDS HistoryQosPolicyKind

Kinds of history.

QoS:

DDS HistoryQosPolicy (p. 758)

Enumerator:

DDS KEEP LAST HISTORY QOS [default] Keep the last depth

samples.

On the publishing side, RTI Connext will only attempt to ke ep the

most recent depth samples of each instance of data (identiﬁed by its

key) managed by the DDSDataWriter (p. 1113).

On the subscribing side, the DDSDataReader (p. 1087) will only

attempt to keep the most recent depth samples received for each in-

stance (identiﬁed by its key) until the application takes them via the

DDSDataReader (p. 1087) ’s take() operation.

DDS KEEP ALL HISTORY QOS Keep all the samples.

On the publishing side, RTI Connext will attempt to keep all samples

(representing each value written) of each instance of data (identiﬁed

by its key) managed by the DDSDataWriter (p. 1113) until they can

be delivered to all subscribers.

On the subscribing side, RTI Connext will attempt to keep all samples

of each instance of data (identiﬁed by its key) managed by the DDS-

DataReader (p. 1087). These samples are kept until the application

takes them from RTI Connext via the take() operation.

5.99.2.2 enum DDS ReﬁlterQosPolicyKind

<<eXtension>> ( p. 199) Kinds of Reﬁltering

QoS:

DDS HistoryQosPolicy (p. 758)

Enumerator:

DDS NONE REFILTER QOS [def ault] Do not ﬁlter existing sam-

ples for a new reader

On the publishing side, when a new reader matches a writer, the writer

can be conﬁgured to ﬁlter previously written samples stored in the

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.99 HISTORY 369

writer queue for the new reader. This option conﬁgures the writer to

not ﬁlter any existing samples for the reader and the reader will do

the ﬁltering.

DDS ALL REFILTER QOS Filter all existing samples for a new

reader.

On the publishing side, when a new reader matches a writer, the writer

can be conﬁgured to ﬁlter previously written samples stored in the

writer queue. This option conﬁgures the writer to ﬁlter all existing

samples for the reader when a new reader is matched to the writer.

DDS ON DEMAND REFILTER QOS Filter existing samples only

when they are requested by the reader.

On the publishing side, when a new reader matches a writer, the writer

can be conﬁgured to ﬁlter previously written samples stored in the

writer queue. This option conﬁgures the writer to ﬁlter only existing

samples that are requested by the reader.

5.99.3 Variable Documentation

5.99.3.1 const char∗ const DDS HISTORY QOS POLICY NAME

Stringiﬁed human-readable name for DDS HistoryQosPolicy (p. 758).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

370 Module Documentation

5.100 DURABILITY SERVICE

Various settings to conﬁgure the external RTI Persistence Service used by

RTI Connext for DataWriters with a DDS DurabilityQosPolicy (p. 614)

setting of DDS PERSISTENT DURABILITY QOS (p. 349) or DDS -

TRANSIENT DURABILITY QOS (p. 349).

Classes

struct DDS DurabilityServiceQosPolicy

Various settings to conﬁgure the external RTI Persistence Service used by

RTI Connext for DataWriters with a DDS DurabilityQosPolicy ( p. 614)

setting of DDS PERSISTENT DURABILITY QOS ( p. 349) or DDS -

TRANSIENT DURABILITY QOS ( p. 349).

Variables

const char ∗const DDS DURABILITYSERVICE QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS DurabilityServiceQosPolicy

( p. 618).

5.100.1 Detailed Description

Various settings to conﬁgure the external RTI Persistence Service used by

RTI Connext for DataWriters with a DDS DurabilityQosPolicy (p. 614)

setting of DDS PERSISTENT DURABILITY QOS (p. 349) or DDS -

TRANSIENT DURABILITY QOS (p. 349).

5.100.2 Variable Documentation

5.100.2.1 const char∗ const DDS DURABILITYSERVICE QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS DurabilityServiceQosPolicy

(p. 618).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.101 RESOURCE LIMITS 371

5.101 RESOURCE LIMITS

Controls the amount of physical memory allocated for DDS entities, if dynamic

allocations are allowed, and how they oc cur. Also controls memory usage among

diﬀerent instance values for keyed topics.

Classes

struct DDS ResourceLimitsQosPolicy

Controls the amount of physical memory allocated for DDS entities, if dy-

namic allocations are allowed, and how they occur. Also controls memory

usage among diﬀerent instance values for keyed topics.

Variables

const char ∗const DDS RESOURCELIMITS QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS ResourceLimitsQosPolicy

( p. 879).

const DDS Long DDS LENGTH UNLIMITED

A special value indicating an unlimited quantity.

5.101.1 Detailed Description

Controls the amount of physical memory allocated for DDS entities, if dynamic

allocations are allowed, and how they oc cur. Also controls memory usage among

diﬀerent instance values for keyed topics.

5.101.2 Variable Documentation

5.101.2.1 const char∗ const DDS RESOURCELIMITS QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS ResourceLimitsQosPolicy

(p. 879).

5.101.2.2 const DDS Long DDS LENGTH UNLIMITED

A special value indicating an unlimited quantity.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

372 Module Documentation

Examples:

HelloWorld subscriber.cxx.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.102 TRANSPORT PRIORITY 373

5.102 TRANSPORT PRIORITY

This QoS policy allows the application to take advantage of transports that are

capable of sending messages with diﬀerent priorities.

Classes

struct DDS TransportPriorityQosPolicy

This QoS policy allows the application to take advantage of transports that

are capable of sending messages with diﬀerent priorities.

Variables

const char ∗const DDS TRANSPORTPRIORITY QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS TransportPriorityQosPolicy

( p. 983).

5.102.1 Detailed Description

This QoS policy allows the application to take advantage of transports that are

capable of sending messages with diﬀerent priorities.

5.102.2 Variable Documentation

5.102.2.1 const char∗ const DDS TRANSPORTPRIORITY QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS TransportPriorityQosPolicy

(p. 983).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

374 Module Documentation

5.103 LIFESPAN

Speciﬁes how long the data written by the DDSDataWriter (p. 1113) is con-

sidered valid.

Classes

struct DDS LifespanQosPolicy

Speciﬁes how long the data written by the DDSDataWriter ( p. 1113) is

considered valid.

Variables

const char ∗const DDS LIFESPAN QOS POLICY NAME

Stringiﬁed human-readable name for DDS LifespanQosPolicy ( p. 773).

5.103.1 Detailed Description

Speciﬁes how long the data written by the DDSDataWriter (p. 1113) is con-

sidered valid.

5.103.2 Variable Documentation

5.103.2.1 const char∗ const DDS LIFESPAN QOS POLICY NAME

Stringiﬁed human-readable name for DDS Life spanQosPolicy (p. 773).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.104 WRITER DATA LIFECYCLE 375

5.104 WRITER DATA LIFECYCLE

Controls how a DataWriter handles the lifecycle of the instances (keys) that it

is registered to manage.

Classes

struct DDS WriterDataLifecycleQosPolicy

Controls how a DDSDataWriter ( p. 1113) handles the lifecy cle of the in-

stances (keys) that it is registered to manage.

Variables

const char ∗const DDS WRITERDATALIFECYCLE QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS -

WriterDataLifecycleQosPolicy ( p. 1071).

5.104.1 Detailed Description

Controls how a DataWriter handles the lifecycle of the instances (keys) that it

is registered to manage.

5.104.2 Variable Documentation

5.104.2.1 const char∗ const DDS WRITERDATALIFECYCLE -

QOS POLICY NAME

Stringiﬁed human-readable name for DDS WriterDataLifecycleQosPolicy

(p. 1071).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

376 Module Documentation

5.105 READER DATA LIFECYCLE

Controls how a DataReader manages the lifecycle of the data that it has receive d.

Classes

struct DDS ReaderDataLifecycleQosPolicy

Controls how a DataReader manages the lifecycle of the data that it has

received.

Variables

const char ∗const DDS READERDATALIFECYCLE QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS -

ReaderDataLifecycleQosPolicy ( p. 859).

5.105.1 Detailed Description

Controls how a DataReader manages the lifecycle of the data that it has receive d.

5.105.2 Variable Documentation

5.105.2.1 const char∗ const DDS READERDATALIFECYCLE -

QOS POLICY NAME

Stringiﬁed human-readable name for DDS ReaderDataLifecycleQosPolicy

(p. 859).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.106 ENTITY FACTORY 377

5.106 ENTITY FACTORY

A QoS policy for all DDSEntity (p. 1253) types that can act as factories for

one or more other DDSEntity (p. 1253) types.

Classes

struct DDS EntityFactoryQosPolicy

A QoS pol icy for all DDSEntity ( p. 1253) types that can act as factories

for one or more other DDSEntity ( p. 1253) types.

Variables

const char ∗const DDS ENTITYFACTORY QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS EntityFactoryQosPolicy

( p. 733).

5.106.1 Detailed Description

A QoS policy for all DDSEntity (p. 1253) types that can act as factories for

one or more other DDSEntity (p. 1253) types.

5.106.2 Variable Documentation

5.106.2.1 const char∗ const DDS ENTITYFACTORY QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS EntityFactoryQosPolicy (p. 733).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

378 Module Documentation

5.107 Extended Qos Support

<<eXtension>> ( p. 199) Types and deﬁnes used in extended QoS policies.

Modules

Thread Settings

The properties of a thread of execution.

Classes

struct DDS RtpsReliableReaderProtocol t

Qos related to reliable reader protocol deﬁned in RTPS.

struct DDS RtpsReliableWriterProtocol t

QoS related to the reliable writer protocol deﬁned in RTPS.

5.107.1 Detailed Description

<<eXtension>> ( p. 199) Types and deﬁnes used in extended QoS policies.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.108 Unicast Settings 379

5.108 Unicast Settings

Unicast communication settings.

Classes

struct DDS TransportUnicastSettings t

Type representing a list of unicast locators.

struct DDS TransportUnicastSettingsSeq

Declares IDL sequence< DDS TransportUnicastSettings t ( p. 989) >.

5.108.1 Detailed Description

Unicast communication settings.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

380 Module Documentation

5.109 Multicast Settings

Multicast communication settings.

Classes

struct DDS TransportMulticastSetti ngs t

Type representing a list of multicast locators.

struct DDS TransportMulticastSetti ngsSeq

Declares IDL sequence< DDS TransportMulticastSettings t ( p. 980) >.

5.109.1 Detailed Description

Multicast communication settings.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.110 Multicast Mapping 381

5.110 Multicast Mapping

Multicast communication mapping.

Classes

struct DDS TransportMulticastMappingFunction t

Type representing an external mapping function.

struct DDS TransportMulticastMapping t

Type representing a list of multicast mapping elements.

struct DDS TransportMulticastMappingSeq

Declares IDL sequence< DDS TransportMulticastMapping t ( p. 971)

5.110.1 Detailed Description

Multicast communication mapping.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

382 Module Documentation

5.111 TRANSPORT SELE CTION

<<eXtension>> ( p. 199) Speciﬁes the physical transports that a DDS-

DataWriter (p. 1113) or DDSDataReader (p. 1087) may use to send or re-

ceive data.

Classes

struct DDS TransportSelecti onQosPolicy

Speciﬁes the physical transports a DDSDataWriter ( p. 1113) or DDS-

DataReader ( p. 1087) may use to send or receive data.

Variables

const char ∗const DDS TRANSPORTSELECTION QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS TransportSelectionQosPolicy

( p. 985).

5.111.1 Detailed Description

<<eXtension>> ( p. 199) Speciﬁes the physical transports that a DDS-

DataWriter (p. 1113) or DDSDataReader (p. 1087) may use to send or re-

ceive data.

5.111.2 Variable Documentation

5.111.2.1 const char∗ const DDS TRANSPORTSELECTION -

QOS POLICY NAME

Stringiﬁed human-readable name for DDS Transp ortSelecti onQosPolicy

(p. 985).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.112 TRANSPORT UNICAST 383

5.112 TRANSPORT UNICAST

<<eXtension>> ( p. 199) Speciﬁes a subset of transports and a port number

that can be used by an Entity to receive data.

Modules

Unicast Settings

Unicast communication settings.

Classes

struct DDS TransportUnicastQosPolicy

Speciﬁes a subset of transports and a port number that can be used by an

Entity to receive data.

Variables

const char ∗const DDS TRANSPORTUNICAST QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS TransportUnicastQosPolicy

( p. 987).

5.112.1 Detailed Description

<<eXtension>> ( p. 199) Speciﬁes a subset of transports and a port number

that can be used by an Entity to receive data.

5.112.2 Variable Documentation

5.112.2.1 const char∗ const DDS TRANSPORTUNICAST QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS TransportUnicastQosPolicy

(p. 987).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

384 Module Documentation

5.113 TRANSPORT MULTICAST

<<eXtension>> ( p. 199) Spec iﬁes the multicast address on which a DDS-

DataReader (p. 1087) wants to receive its data. I t can also specify a port

number, as well as a subset of the available (at the DDSDomainParticipant

(p. 1139) level) transports with which to receive the multicast data.

Modules

Multicast Settings

Multicast communication settings.

Multicast Mapping

Multicast communication mapping.

Classes

struct DDS TransportMulticastQosPolicy

Speciﬁes the multicast address on which a DDSDataReader ( p. 1087) wants

to receive its data. It can also specify a port number as well as a subset of

the available (at the DDSDomainParticipant ( p. 1139) level) transports

with which to receive the multicast data.

Enumerations

enum DDS TransportMulticastQosPolicyKind {

DDS AUTOMATIC TRANSPORT MULTICAST QOS,

DDS UNICAST ONLY TRANSPORT MULTICAST QOS }

Transport Multicast Policy Kind.

Variables

const char ∗const DDS TRANSPORTMULTICAST QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS TransportMulticastQosPolicy

( p. 978).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.113 TRANSPORT MULTICAST 385

5.113.1 Detailed Description

<<eXtension>> ( p. 199) Spec iﬁes the multicast address on which a DDS-

DataReader (p. 1087) wants to receive its data. I t can also specify a port

number, as well as a subset of the available (at the DDSDomainParticipant

(p. 1139) level) transports with which to receive the multicast data.

5.113.2 Enumeration Type Documentation

5.113.2.1 enum DDS TransportMulticastQosPolicyKind

Transport Multicast Policy Kind.

See also:

DDS TransportMulticastQosPolicy (p. 978)

Enumerator:

DDS AUTOMATIC TR ANSPORT MULTICAST QOS Selects

the multicast address automatically.

NOTE: This s etting is required when using the DDS -

TransportMulticastMappingQosPolicy (p. 975).

DDS UNICAST ONLY TRANSPORT MULTICAST QOS

Selects a unicast-only mode.

5.113.3 Variable Documentation

5.113.3.1 const char∗ const DDS TRANSPORTMULTICAST -

QOS POLICY NAME

Stringiﬁed human-readable name for DDS TransportMulticastQosPolicy

(p. 978).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

386 Module Documentation

5.114 TRANSPORT MULTICAST -

MAPPING

<<eXtension>> ( p. 199) Speciﬁes a list of topic expressions and addresses

that can be used by an Entity with a speciﬁc topic name to receive data.

Classes

struct DDS TransportMulticastMappingQosPolicy

Speciﬁes a list of topic expressions and multicast addresses that can be used

by an Entity with a speciﬁc topic name to receive data.

Variables

const char ∗const DDS TRANSPORTMULTICASTMAPPING -

QOS POLICY NAME

Stringiﬁed human-readable name for DDS -

TransportMulticastMappingQosPolicy ( p. 975).

5.114.1 Detailed Description

<<eXtension>> ( p. 199) Speciﬁes a list of topic expressions and addresses

that can be used by an Entity with a speciﬁc topic name to receive data.

5.114.2 Variable Documentation

5.114.2.1 const char∗ const DDS -

TRANSPORTMULTICASTMAPPING -

QOS POLICY NAME

Stringiﬁed human-readable name for DDS -

TransportMulticastMappingQosPolicy (p. 975).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.115 DISCOVERY 387

5.115 DISCOVERY

<<eXtension>> ( p. 199) Speciﬁes the attributes required to discover partic-

ipants in the domain.

Modules

NDDS DISCOVERY PEERS

Environment variable or a ﬁle that speciﬁes the default values

of DDS DiscoveryQosPolicy::initial peers ( p. 583) and DDS -

DiscoveryQosPolicy::multicast receive addresse s ( p. 584) contained in

the DDS DomainParticipantQos::discovery ( p. 591) qos policy.

Classes

struct DDS DiscoveryQosPolicy

Conﬁgures the mechanism used by the middleware to automatically discover

and connect with new remote applications.

Variables

const char ∗const DDS DISCOVERY QOS POLICY NAME

Stringiﬁed human-readable name for DDS DiscoveryQosPolicy ( p. 582).

5.115.1 Detailed Description

<<eXtension>> ( p. 199) Speciﬁes the attributes required to discover partic-

ipants in the domain.

5.115.2 Variable Documentation

5.115.2.1 const char∗ const DDS DISCOVERY QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS

DiscoveryQosPolicy (p. 582).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

388 Module Documentation

5.116 NDDS DISCOVERY PEER S

Environment variable or a ﬁle that speciﬁes the default values

of DDS DiscoveryQosPolicy::initial peers (p. 583) and DDS -

DiscoveryQosPolicy::multicast receive addresses (p. 584) contained

in the DDS DomainParticipantQos::discovery (p. 591) qos policy.

The default value of the DDS DomainParticipantQos (p. 588) is obtained by

calling DDSDomainParticipantFactory::get default participant qos()

(p. 1224).

NDDS DISCOVERY PEERS speciﬁes the default value of the

DDS DiscoveryQosPolicy::initial peers (p. 583) and DDS -

DiscoveryQosPolicy::multicast receive addresses (p. 584) ﬁelds, when

the default participant QoS policies have not been explictly set by the user

(i.e., DDSDomainParticipantFactory::set default participant qos()

(p. 1222) has never been called or was called using DDS PARTICIPANT -

QOS DEFAULT (p. 35)).

If NDDS DISCOVERY PEERS does not contain a multicast address, then the

string s equence DDS DiscoveryQosPolicy::multicast receive addresses

(p. 584) is cleared and the RTI discovery proce ss will not listen for discovery

messages via multicast.

If NDDS DISCOVERY PEERS contains one or more multicast addresses, the

addresses will be stored in DDS DiscoveryQosPolicy::multicast receive -

addresses (p. 584), starting at element 0. They will be stored in the order in

which they appear in NDDS DISCOVERY PEERS.

Note: IPv4 multicast addresses must have a preﬁx. Therefore, when using the

UDPv6 transport: if there are any IPv4 multicast addresses in the peers list,

make sure they have ”udpv4://” in front of them (such as udpv4://239.255.0.1).

Note: Currently, RTI Connext will only listen for discovery traﬃc on the ﬁrst

multicast address (element 0) in DDS DiscoveryQosPolicy::multicast -

receive addresses (p. 584).

NDDS DISCOVERY PEERS provides a mechanism to dynamically switch the

discovery conﬁguration of an RTI Connext application without recompilation.

The application programmer is free to not use the default values; instead use

values supplied by other means.

NDDS DISCOVERY PEERS can be speciﬁed either in an environment variable

as comma (’,’) separated "peer descriptors" (see Peer Descriptor Format

(p. 389)) or in a ﬁle. These formats are described below.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.116 NDDS DISCOVERY PEERS 389

5.116.1 Peer Descriptor Format

A peer descriptor string speciﬁes a range of participants at a given locator.

Peer descriptor strings are used in the DDS DiscoveryQosPolicy::initial -

peers (p. 583) ﬁeld and the DDSDomainParticipant::add peer() (p. 1199)

operation.

The anatomy of a peer descriptor is illustrated below using a special ”StarFab-

ric” transport example.

A peer descriptor consists of:

optional Participant ID. If a simple integer is spec iﬁed, it indicates the maximum

participant ID to be contacted by the RTI Connext discovery mechanism

at the given locator. If that integer is enclosed in square brackets (e.g.:

[2]) only that Participant ID will be used. You can also specify a range

in the form of [a,b]: in this case only the Participant IDs in that speciﬁc

range are contacted. If omitted, a default value of 4 is implied.

Locator. See Locator Format (p. 389).

These are separated by the ’@’ character. The separator may be omitted if a

participant ID limit is not explictly speciﬁed.

Note that the ”participant ID limit” only applies to unicast locators; it is ig-

nored for multicast locators (and therefore should be omitted for multicast peer

descriptors).

5.116.1.1 Locator Format

A locator string speciﬁes a transport and an address in string format. Locators

are used to form peer descriptors. A locator is equivalent to a peer descriptor

with the default maximum participant ID.

A locator consists of:

optional Transport name (alias or class). This identiﬁes the set of transport plu-

gins (Transport Aliases (p. 125)) that may be used to parse the address

portion of the locator. Note that a transport class name is an implicit alias

that is used to refer to all the transport plugin instances of that class.

optional Address. See Address Format (p. 390).

These are separated by the ”//:” string. The separator is speciﬁed if and only

if a transport name is speciﬁed.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

390 Module Documentation

If a transport name is speciﬁed, the address may b e omitted; in that case, all

the unicast addresses (across all transport plugin instances) associated with the

transport class are implied. Thus, a locator string may specify several addresses.

If an address is speciﬁed, the transport name and the separator string may b e

omitted; in that case all the available transport plugins (for the DDSEntity

(p. 1253)) may be used to parse the address string.

5.116.1.2 Address Format

An address string speciﬁes a transport-independent network address that qual-

iﬁes a transport-dependent address string. Addresses are use d to form lo-

cators. Addresses are also used in DDS DiscoveryQosPolicy::multicast -

receive addresses (p. 584), and DDS TransportMulticastSettings -

t::receive address (p. 981) ﬁelds. An address is equivalent to a locator in

which the transport name and separator are omitted.

An address consists of:

optional Network Address. An address in IPv4 or IPv6 string notation. If omit-

ted, the network address of the transp ort is implied (Transport Network

Address (p. 128)).

optional Transport Address. A string that is passed to the transport for process-

ing. The transp ort maps this string into NDDS Transport Property -

t::address bit count (p. 1524) bits. If omitted the network address is

used as the fully qualiﬁed address.

These are separated by the ’#’ character. If a separator is speciﬁed, it must be

followed by a non-empty string which is passed to the transport plugin.

The bits resulting from the transport address string are prepended with

the network address. The least signiﬁcant NDDS Transport Property -

t::address bit count (p. 1524) bits of the network address are ignored

(Transport Network Address (p. 128)).

If the separator is omitted and the string is not a valid IPv4 or IPv6 address,

it is treated as a transport address with an implicit network address (of the

transport plugin).

5.116.2 NDDS DISCOVERY PEERS Environment Vari-

able Format

NDDS DISCOVERY PEERS can be speciﬁed via an environment variable of

the same name, consisting of a sequence of peer descriptors separated by the

comma (’,’) character.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.116 NDDS DISCOVERY PEERS 391

Examples

Multicast (maximum participant ID is irrelevant)

239.255.0.1

Default m aximum participant ID on localhost

localhost

Default m aximum participant ID on host 192.168.1.1 (IPv4)

192.168.1.1

Default m aximum participant ID on host FAA0::0 (IPv6)

FAA0::1

Default maximum participant ID on host FAA0::0#localhost (could be a UDPv4

transport plugin registered at network address of FAA0::0) (IPv6)

FAA0::0#localhost

Default maximum participant ID on host himalaya accessed using the ”udpv4”

transport plugin(s) (IPv4)

udpv4://himalaya

Default maximum participant ID on localhost using the ”udpv4” transport plu-

gin(s) registered at network address FAA0::0

udpv4://FAA0::0#localhost

Default maximum participant ID on all unicast addresses acces sed via the

”udpv4” (UDPv4) transport plugin(s)

udpv4://

Default m aximum participant ID on host 0/0/R (StarFabric)

0/0/R

#0/0/R

Default maximum participant ID on host 0/0/R (StarFabric) using the ”star-

fabric” (StarFabric) transport plugin(s)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

392 Module Documentation

starfabric://0/0/R

starfabric://#0/0/R

Default maximum participant ID on host 0/0/R (StarFabric) using the ”star-

fabric” (StarFabric) transport plugin(s) registered at network address FAA0::0

starfabric://FBB0::0#0/0/R

Default maximum participant ID on all unicast addresses access ed via the ”star-

fabric” (StarFabric) transport plugin(s)

starfabric://

Default maximum participant ID on all unicast addresses acces sed via the

”shmem” (shared memory) transport plugin(s)

shmem://

Default maximum participant ID on all unicast addresses acces sed via the

”shmem” (shared memory) transport plugin(s) registered at network address

FCC0::0

shmem://FCC0::0

Default m aximum participant ID on hosts himalaya and gangotri

himalaya,gangotri

Maximum participant ID of 1 on hosts himalaya and gangotri

1@himalaya,1@gangotri

Combinations of above

239.255.0.1,lo c alhost,192.168.1.1,0/0/R

FAA0::1,FAA0::0#localhost,FBB0::0#0/0/R

udpv4://himalaya,udpv4://FAA0::0#localhost,#0/0/R

starfabric://0/0/R,starfabric://FBB0::0#0/0/R,shmem://

starfabric://,shmem://FCC 0::0,1@himalaya,1@gangotri

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.116 NDDS DISCOVERY PEERS 393

5.116.3 NDDS DISCOVERY PEERS File Format

NDDS DISCOVERY PEERS can be sp e ciﬁed via a ﬁle of the same name in the

program’s current working directory. A NDDS DISCOVERY PEERS ﬁle would

contain a sequence of peer descriptors separated by whitespace or the comma

(’,’) character. The ﬁle m ay also contain comments starting with a semic olon

(’;’) character till the end of the line.

Example:

;; NDDS_DISCOVERY_PEERS - Default Discovery Configuration File

;;

;; NOTE:

;; 1. This file must be in the current working directory, i.e.

;; in the folder from which the application is launched.

;;

;; 2. This file takes precedence over the environment variable NDDS_D ISCO VER Y_PE ERS

;;

;; Multicast

239.255.0.1 ; The default RTI C onne xt discovery multicast address

;; Unicast

localhost,192.168.1.1 ; A comma ca n be used a separator

FAA0::1 FAA0::0#localhost ; Whitespace can be used as a separator

1@himalaya ; Maximum participant ID of 1 on ’himalaya’

1@gangotri

;; UDPv4

udpv4://himalaya ; ’himalaya’ via ’udpv4’ transport plugin(s)

udpv4://FAA0::0#localhost ; ’localhost’ via ’updv4’ transport

; plugin regi ster ed at network address FAA0::0

;; Shared Memory

shmem:// ; All ’shmem’ transport plugin(s)

builtin.shmem:// ; The builtin ’shmem’ transport plugin

shmem://FCC0::0 ; Shared memory transport plugin registered

; at network address FCC0::0

;; StarFabric

0/0/R ; StarFabric node 0/0/R

starfabric://0/0/R ; 0/0/R accessed via ’starfabric’

; transport plugin(s)

starfabric://FBB0::0#0/0/R ; StarFabric transport plugin register ed

; at network address FBB0::0

starfabric:// ; All ’starfabric’ transport plugin(s)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

394 Module Documentation

5.116.4 NDDS DISCOVERY PEERS Precedence

If the current working directory from which the RTI Connext application is

launched contains a ﬁle called NDDS DISCOVERY PEERS, and an environ-

ment variable named NDDS DISCOVERY PEERS is also deﬁned, the ﬁle takes

precedence; the environment variable is ignored.

5.116.5 NDDS DISCOVERY PEERS Default Value

If NDDS DISCOVERY PEERS is not speciﬁed (either as a ﬁle in the current

working directory, or as an environment variable), it implicitly defaults to the

follow ing.

;; Multicast (only on pla tfor ms which allow UDPv4 multicast out of the box)

;;

;; This allows any RTI Connext applications anywhere on the local network to

;; discover each other ov er UDPv4.

builtin.udpv4://239.255.0.1 ; RTI Connext’s default discovery mult icas t address

;; Unicast - UDPv4 (on all platforms)

;;

;; This allows two RTI Connext applications using participant IDs up to the maximum

;; default participant ID on the local host and domain to discover each

;; other over UDP/IPv4.

builtin.udpv4://127.0.0.1

;; Unicast - Shared Memor y (only on platforms that support shared memory)

;;

;; This allows two RTI Connext applications using participant IDs up to the maximum

;; default participant ID on the local host and domain to discover each

;; other over shared memo ry.

builtin.shmem://

5.116.6 Builtin Transport Class Names

The class names for the builtin transport plugins are:

shmem - ::Shared Memory Transport (p. 257)

udpv4 - ::UDPv4 Transport (p. 265)

udpv6 - ::UDPv6 Transport (p. 275)

These may be used as the transport names in the Locator Format (p. 389).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.116 NDDS DISCOVERY PEERS 395

5.116.7 NDDS DISCOVERY PEERS and Local Host

Communication

Supp ose you want to communicate with other RTI Connext applications on the

same host and you are setting NDDS DISCOVERY PEERS explicitly (generally

in order to use unicast discovery with applications on other hosts).

If the local host platform does not support the shared memory transport, then

you can include the name of the local host in the NDDS DISCOVERY PEERS

list.

If the local host platform supports the shared memory transport, then you can

do one of the following:

Include ”shmem://” in the NDDS DISCOVERY PEERS list. This will

cause shared memory to be used for discovery and data traﬃc for appli-

cations on the same host.

or:

Include the name of the local host in the NDDS DISCOVERY -

PEERS list and disable the shared memory transport in the DDS -

TransportBuiltinQosPolicy (p. 969) of the DDSDomainParticipant

(p. 1139). This will cause UDP loopback to be used for discovery and data

traﬃc for applications on the same host.

(To check if your platform supports shared memory, see the Platform Notes.)

See also:

DDS DiscoveryQosPolicy::multicast receive addresses (p. 584)

DDS DiscoveryQosPolicy::initial peers (p. 583)

DDSDomainParticipant::add peer() (p. 1199)

DDS PARTICIPANT QOS DEFAULT (p. 35)

DDSDomainParticipantFactory::get default participant qos()

(p. 1224)

Transport Aliases (p. 125)

Transport Network Address (p. 128)

NDDSTransportSupport::register transport() (p. 1560)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

396 Module Documentation

5.117 TRANSPORT BUILTIN

<<eXtension>> ( p. 199) Speciﬁes which built-in transports are used.

Classes

struct DDS TransportBuilt inQosPolicy

Speciﬁes which built-in transports are used.

Deﬁnes

#deﬁne DDS TRANSPORTBUILTIN MASK NONE

None of the built-in transports will be registered automatically when the

DDSDomainParticipant ( p. 1139) is enabled. The user must explictly

( p. 1560).

#deﬁne DDS TRANSPORTBUILTIN MASK DEFAULT

The default value of DDS TransportBuiltinQosPolicy::mask ( p. 970).

#deﬁne DDS TRANSPORTBUILTIN MASK ALL

All the available built-in transports are registered automatically when the

DDSDomainParticipant ( p. 1139) is enabled.

Typedefs

typedef DDS Long DDS TransportBuiltinKindMask

A mask of DDS TransportBuiltinKind ( p. 398) bits.

Enumerations

enum DDS TransportBuil tinKi nd {

DDS TRANSPORTBUILTIN UDPv4,

DDS TRANSPORTBUILTIN SHMEM ,

DDS TRANSPORTBUILTIN UDPv6 }

Built-in transport kind.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.117 TRANSPORT BUILTIN 397

Variables

const char ∗const DDS TRANSPORTBUILTIN QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS TransportBuiltinQosPolicy

( p. 969).

const char ∗const DDS TRANSPORTBUILTIN SHMEM -

ALIAS

Alias name for the shared memory built-in transport.

const char ∗const DDS TRANSPORTBUILTIN UDPv4 ALIAS

Alias name for the UDPv4 built-in transport.

const char ∗const DDS TRANSPORTBUILTIN UDPv6 ALIAS

Alias name for the UDPv6 built-in transport.

5.117.1 Detailed Description

<<eXtension>> ( p. 199) Speciﬁes which built-in transports are used.

See also:

Changing the automatically registered built-in transports (p. 181)

5.117.2 Deﬁne Documentation

5.117.2.1 #deﬁne DDS TRANSPORTBUILTIN MASK NONE

None of the built-in transports will be registered automatically when the DDS-

DomainParticipant (p. 1139) is enabled. The user must explictly register

transports using NDDSTransportSupport::register transport (p. 1560).

See also:

DDS TransportBuiltinKindMask (p. 398)

5.117.2.2 #deﬁne DDS TRANSPORTBUILTIN MASK DEFAULT

The default value of DDS TransportBuiltinQosPolicy::mask (p. 970).

The set of builtin transport plugins that will be automatically registered with

the participant by default. The user can register additional transports using

NDDSTransportSupport::register transport (p. 1560).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

398 Module Documentation

See also:

DDS TransportBuiltinKindMask (p. 398)

5.117.2.3 #deﬁne DDS TRANSPORTBUILTIN MASK ALL

All the available built-in transports are registered automatically when the DDS-

DomainParticipant (p. 1139) is enabled.

See also:

DDS TransportBuiltinKindMask (p. 398)

5.117.3 Typedef Documentation

5.117.3.1 typedef DDS Long DDS TransportBuiltinKindMask

A mask of DDS TransportBuiltinKind (p. 398) bits.

QoS:

DDS TransportBuiltinQosPolicy (p. 969)

5.117.4 Enumeration Type Documentation

5.117.4.1 enum DDS TransportBuiltinKind

Built-in transport kind.

See also:

DDS TransportBuiltinKindMask (p. 398)

Enumerator:

DDS TRANSPORTBUILTIN UDPv4 Built-in UDPv4 transport,

::UDPv4 Transport (p. 265).

DDS TRANSPORTBUILTIN SHMEM Built-in shared mem ory

transport, ::Shared Memory Transport (p. 257).

DDS TRANSPORTBUILTIN UDPv6 Built-in UDPv6 transport,

::UDPv6 Transport (p. 275).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.117 TRANSPORT BUILTIN 399

5.117.5 Variable Documentation

5.117.5.1 const char∗ const DDS TRANSPORTBUILTIN QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS TransportBuiltinQosPolicy

(p. 969).

5.117.5.2 const char∗ const DDS TRANSPORTBUILTIN -

SHMEM ALIAS

Alias name for the shared memory built-in transport.

5.117.5.3 const char∗ const DDS TRANSPORTBUILTIN UDPv4 -

ALIAS

Alias name for the UDPv4 built-in transport.

5.117.5.4 const char∗ const DDS TRANSPORTBUILTIN UDPv6 -

ALIAS

Alias name for the UDPv6 built-in transport.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

400 Module Documentation

5.118 WIRE PROTOCOL

<<eXtension>> ( p. 199) Speciﬁes the wire protocol related attributes for the

DDSDomainParticipant (p. 1139).

Classes

struct DDS RtpsWellKnownPorts t

RTPS well-known port mapping conﬁguration.

struct DDS WireProtocolQosPolicy

Speciﬁes the wire-protocol-related attributes for the DDSDomainPartici-

pant ( p. 1139).

Deﬁnes

#deﬁne DDS RTPS RESERVED PORT MASK DEFAULT

The default value of DDS WireProtoco lQosPolicy::rtps reserved port -

mask ( p. 1065).

#deﬁne DDS RTPS RESERVED PORT MASK NONE

No bits are set.

#deﬁne DDS RTPS RESERVED PORT MASK ALL

All bits are set.

Typedefs

typedef DDS Long DDS RtpsReservedPortKi ndMask

A mask of DDS RtpsReservedPortKind ( p. 403) bits.

Enumerations

enum DDS RtpsReservedPortKind {

DDS RTPS RESERVED PORT BUILTIN UNICAST = 0x0001

<< 0,

DDS RTPS RESERVED PORT BUILTIN MULTICAST =

0x0001 << 1,

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.118 WIRE PROTOCOL 401

DDS RTPS RESERVED PORT USER UNICAST = 0x0001 <<

DDS RTPS RESERVED PORT USER MULTICAST = 0x0001

<< 3 }

RTPS reserved port kind, used to identify the types of ports that can be re-

served on domain participant enable.

enum DDS WireProtocolQosPolicyAutoKind {

DDS RTPS AUTO ID FROM IP,

DDS RTPS AUTO ID FROM MAC }

Kind of auto mechanism used to calculate the GUID preﬁx.

Variables

struct DDS RtpsWellKnownPorts t DDS RTI BACKWARDS -

COMPATIBLE RTPS WELL KNOWN PORTS

Assign to use well-known port mappings which are compatible with previous

versions of the RTI Connext middleware.

struct DDS RtpsWellKnownPorts t DDS INTEROPERABLE -

RTPS WELL KNOWN PORTS

Assign to use well-known port mappings which are compliant with OMG’s

DDS Interoperability Wire Protocol.

const char ∗const DDS WIREPROTOCOL QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS WireProtocolQosPolicy

( p. 1059).

5.118.1 Detailed Description

<<eXtension>> ( p. 199) Speciﬁes the wire protocol related attributes for the

DDSDomainParticipant (p. 1139).

5.118.2 Deﬁne Documentation

5.118.2.1 #deﬁne DDS RTPS RESERVED PORT MASK -

DEFAULT

Value:

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

402 Module Documentation

((DDS_RtpsReservedPortKindMask) DDS_RTPS_RESERVED_PORT_BUIL TIN_ UNIC AST \

| DDS_RTPS_RESERVED_PORT_BUILTIN_MULTICAST | DDS_RTPS_RESERVED_PORT_USER_UNICAST)

The default value of DDS WireProtocolQosPolicy::rtps reserved port -

mask (p. 1065).

Most of the ports that may be needed by DDS will be reserved by the transport

when the participant is enabled. With this value set, failure to allocate a port

that is computed based on the DDS RtpsWellKnownPorts t (p. 905) will

be detected at this time and the enable operation will fail.

This setting will avoid reserving the usertraﬃc multicast port, which is not

actually used unless there are DataReaders that enable multicast but fail to

specify a port.

Automatic participant ID selection will be based on ﬁnding a participant index

with both the discovery (metatraﬃc) unicast port and usertraﬃc unicast port

available.

See also:

DDS RtpsReservedPortKindMask (p. 403)

5.118.2.2 #deﬁne DDS RTPS RESERVED PORT MASK NONE

No bits are set.

None of the ports that are needed by DDS will b e allocated until they are

speciﬁcally required. With this value set, automatic participant Id selection

will be based on selecting a port for discovery (metatraﬃc) unicast traﬃc on a

single transport.

See also:

DDS RtpsReservedPortKindMask (p. 403)

5.118.2.3 #deﬁne DDS RTPS RESERVED PORT MASK ALL

All bits are set.

All of the ports that may be needed by DDS will be reserved when the partici-

pant is enabled. With this value set, failure to allocate a port that is computed

based on the DDS RtpsWellKnownPorts t (p. 905) will be detected at this

time, and the enable operation will fail.

Note that this will also reserve the usertraﬃc multicast port which is not

actually used unless there are DataReaders that enable multicast but fail to

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.118 WIRE PROTOCOL 403

specify a port. To avoid unnecesary resource usage for these ports, use RTPS -

RESERVED PORT MASK DEFAULT.

Automatic participant ID selection will be based on ﬁnding a participant index

with both the discovery (metatraﬃc) unicast port and usertraﬃc unicast port

available.

See also:

DDS RtpsReservedPortKindMask (p. 403)

5.118.3 Typedef Documentation

5.118.3.1 typedef DDS Long DDS RtpsReservedPortKindMask

A mask of DDS RtpsReservedPortKind (p. 403) bits.

QoS:

DDS WireProtocolQosPolicy (p. 1059)

5.118.4 Enumeration Type Documentation

5.118.4.1 enum DDS RtpsReservedPortKind

RTPS reserved port kind, used to identify the types of ports that can be reserved

on domain participant enable.

See also:

DDS WireProtocolQosPolicy::rtps reserved port mask (p. 1065)

Enumerator:

DDS RTPS RESERVED PORT BUILTIN UNICAST Selec t the

metatraﬃc unicast port.

DDS RTPS RESERVED PORT BUILTIN MULTICAST Select

the metatraﬃc multicast port.

DDS RTPS RESERVED PORT USER UNICAST Select the

usertraﬃc unicast port.

DDS RTPS RESERVED PORT USER MULTICAST Select the

usertraﬃc multicast port.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

404 Module Documentation

5.118.4.2 enum DDS WireProtocolQosPolicyAutoKind

Kind of auto mechanism used to calculate the GUID preﬁx.

See also:

DDS WireProtocolQosPolicy::rtps auto id kind (p. 1066)

Enumerator:

DDS RTPS AUTO ID FROM IP Select the IPv4 based algorithm.

DDS RTPS AUTO ID FROM MAC Select the MAC based algo-

rithm.

Note to Solaris Users: To use DDS RTPS AUTO ID FROM MAC,

you must run the RTI Connext application while logged in as ’root.’

5.118.5 Variable Documentation

5.118.5.1 struct DDS RtpsWellKnownPorts t

DDS RTI BACKWARDS COMPATIBLE RTPS -

WELL KNOWN PORTS

Assign to use well-known port mappings which are compatible with previous

versions of the RTI Connext middleware.

Assign DDS WireProtocolQosPolicy::rtps well known ports (p. 1065)

to this value to remain compatible with previous versions of the RTI Connext

middleware that used ﬁxed port mappings.

The following are the rtps well known ports values for DDS RTI -

BACKWARDS COMPATIBLE RTPS WELL KNOWN PORTS

(p. 404):

port base = 7400

domain id gain = 10

participant id gain = 1000

builtin multicast port offset = 2

builtin unicast port offset = 0

user multicast port offset = 1

user unicast port offset = 3

These settings are not compliant with OMG’s DDS Interoperability Wire Proto-

col. To comply with the speciﬁcation, please use DDS INTEROPERABLE -

RTPS WELL KNOWN PORTS (p. 405).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.118 WIRE PROTOCOL 405

See also:

DDS WireProtocolQosPolicy::rtps well known ports (p. 1065)

DDS INTEROPERABLE RTPS WELL KNOWN PORTS

(p. 405)

5.118.5.2 struct DDS RtpsWellKnownPorts t DDS -

INTEROPERABLE RTPS WELL KNOWN PORTS

Assign to use well-known port mappings which are compliant with OMG’s DDS

Interoperability Wire Protocol.

Assign DDS WireProtocolQosPolicy::rtps well known ports (p. 1065)

to this value to use well-known port mappings which are compliant with OMG’s

DDS Interoperability Wire Protocol.

The following are the rtps well known ports values for DDS -

INTEROPERABLE RTPS WELL KNOWN PORTS (p. 405):

port base = 7400

domain id gain = 250

participant id gain = 2

builtin multicast port offset = 0

builtin unicast port offset = 10

user multicast port offset = 1

user unicast port offset = 11

Assuming a maximum port number of 65535 (UDPv4), the above settings enable

the use of about 230 domains with up to 120 Participants per node per domain.

These settings are not backwards com patible with previous versions of the

RTI Connext middleware that used ﬁxed port mappings. For backwards com-

pability, please use DDS RTI BACKWARDS COMPATIBLE RTPS -

WELL KNOWN PORTS (p. 404).

See also:

DDS WireProtocolQosPolicy::rtps well known ports (p. 1065)

DDS RTI BACKWARDS COMPATIBLE RTPS WELL -

KNOWN PORTS (p. 404)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

406 Module Documentation

5.118.5.3 const char∗ const DDS WIREPROTOCOL QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS WireProtocolQosPolicy

(p. 1059).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.119 DATA READER RESOURCE LIMITS 407

5.119 DATA READER RESOURCE LIMITS

<<eXtension>> ( p. 199) Various settings that conﬁgure how DataReaders

allocate and use physical memory for internal resources.

Classes

struct DDS DataReaderResourceLimitsQosPolicy

Various settings that conﬁgure how a DDSDataReader ( p. 1087) allocates

and uses physical memory for internal resources.

Variables

const char ∗const DDS DATAREADERRESOURCELIMITS -

QOS POLICY NAME

Stringiﬁed human-readable name for DDS -

DataReaderResourceLimitsQosPolicy ( p. 521).

const DDS Long DDS AUTO MAX TOTAL INSTANCES

<<eXtension>> (p. 199) This value is used to make DDS -

DataReaderResourceLimitsQosPolicy::max total instances ( p. 530)

equal to DDS ResourceLimitsQosPolicy::max instances ( p. 882).

5.119.1 Detailed Description

<<eXtension>> ( p. 199) Various settings that conﬁgure how DataReaders

allocate and use physical memory for internal resources.

5.119.2 Variable Documentation

5.119.2.1 const char∗ const DDS -

DATAREADERRESOURCELIMITS -

QOS POLICY NAME

Stringiﬁed human-readable name for DDS -

DataReaderResourceLimitsQosPolicy (p. 521).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

408 Module Documentation

5.119.2.2 const DDS Long DDS AUTO MAX TOTAL -

INSTANCES

<<eXtension>> ( p. 199) This value is used to make DDS -

DataReaderResourceLimitsQosPolicy::max total instances (p. 530)

equal to DDS ResourceLimitsQosPolicy::max instances (p. 882).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.120 DATA WRITER RESOURCE LIMITS 409

5.120 DATA WRITER RESOURCE LIMITS

<<eXtension>> ( p. 199) Various settings that conﬁgure how a DDS-

DataWriter (p. 1113) allocates and uses physical memory for internal re-

sources.

Classes

struct DDS DataWriterResourceLimitsQosPolicy

Various settings that conﬁgure how a DDSDataWriter ( p. 1113) allocates

and uses physical memory for internal resources.

Enumerations

enum DDS DataWriterResourceLimitsInstanceReplacementKind

{

DDS UNREGISTERED INSTANCE REPLACEMENT,

DDS ALIVE INSTANCE REPLACEMENT,

DDS DISPOSED INSTANCE REPLACEMENT,

DDS ALIVE THEN DISPOSED INSTANCE -

REPLACEMENT,

DDS DISPOSED THEN ALIVE INSTANCE -

REPLACEMENT,

DDS ALIVE OR DISPOSED INSTANCE REPLACEMENT

}

Sets the kinds of instances that can be replaced when instance resource limits

are reached.

Variables

const char ∗const DDS DATAWRITERRESOURCELIMITS -

QOS POLICY NAME

Stringiﬁed human-readable name for DDS -

DataWriterResourceLimitsQosPolicy ( p. 560).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

410 Module Documentation

5.120.1 Detailed Description

<<eXtension>> ( p. 199) Various settings that conﬁgure how a DDS-

DataWriter (p. 1113) allocates and uses physical memory for internal re-

sources.

5.120.2 Enumeration Type Documentation

5.120.2.1 enum DDS -

DataWriterResourceLimitsInstanceReplacementKind

Sets the kinds of instances that can be replaced when instance resource limits

are reached.

When DDS ResourceLimitsQosPolicy::max instances (p. 882) is reached,

a DDSDataWriter (p. 1113) will try to make room for a new instance by

attempting to reclaim an existing instance based on the instance replacement

kind speciﬁed by DDS DataWriterResourceLimitsQosPolicy:: instance -

replacement (p. 563).

Only instances whose states match the speciﬁed kinds are eligible to be replaced.

In addition, an instance must have had all of its samples fully acknowledged for

it to be considered replaceable.

For all kinds, a DDSDataWriter (p. 1113) will replace the oldest instance sat-

isfying that kind. For example, when the kind is DDS UNREGISTERED -

INSTANCE REPLACEMENT (p. 411), a DDSDataWriter (p. 1113) will

remove the oldest fully acknowledged unregistered instance, if such an instance

exists.

If no replaceable instance exists, the invoked function will either return with

an appropriate out-of-resources return code, or in the case of a write, it may

ﬁrst block to wait for an instance to be acknowledged. Otherwise, the DDS-

DataWriter (p. 1113) will replace the old instance with the new instance, and

invoke, if available, the DDS DataWriterListener InstanceReplacedCallback to

notify the user about an instance being replaced.

A DDSDataWriter (p. 1113) checks for replaceable instances in the following

order, s topping once a replaceable instance is found:

If DDS DataWriterResourceLimitsQosPolicy::replace empty -

instances (p. 564) is DDS BOOLEAN TRUE (p. 298), a DDSDataWriter

(p. 1113) ﬁrst tries replacing instances that have no samples. These

empty instances can be unregistered, disposed, or alive. Next, a DDS-

DataWriter (p. 1113) tries replacing unregistered instances. Since an

unregistered instance indicates that the DDSDataWriter (p. 1113) is

done modifying it, unregistered instances are replaced before instances

of any other state (alive, disposed). This is the same as the DDS -

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.120 DATA WRITER RESOURCE LIMITS 411

UNREGISTERED INSTANCE REPLACEMENT (p. 411) kind. Then,

a DDSDataWriter (p. 1113) tries replacing what is speciﬁed by DDS -

DataWriterResourceLimitsQosPolicy::instance replacement (p. 563).

With unregistered instances already checked, this leaves alive and disposed

instances. When both alive and disposed instances may be replaced, the kind

speciﬁes whether the particular order matters (e.g. DISPOSED THEN ALIVE,

ALIVE THEN DISPOSED) or not (ALIVE OR DISPOSED).

QoS:

DDS DataWriterResourceLimitsQosPolicy (p. 560)

Enumerator:

DDS UNREGISTERED INSTANCE REPLACEMENT Allows

a DDSDataWriter (p. 1113) to reclaim unregistered acknowledged

instances.

By default all instance replacement kinds ﬁrst attempt to re-

claim an unregistered acknowledged instance. Used in DDS -

DataWriterResourceLimitsQosPolicy::instance replacement

(p. 563) [default]

DDS ALIVE INSTANCE REPLACEMENT Allows a DDS-

DataWriter (p. 1113) to reclaim alive acknowledged instances.

When an unregistered acknowledged instance is not available to re-

claim, this kind allows a DDSDataWriter (p. 1113) to reclaim an

alive acknowledged instance, where an alive instance is a registered,

non-disp os ed instance. The least recently registered or written alive

instance will be reclaimed.

DDS DISPOSED INSTANCE REPLACEMENT Allows a DDS-

DataWriter (p. 1113) to reclaim disposed acknowledged instances.

When an unregistered acknowledged instance is not available to re-

claim, this kind allows a DDSDataWriter (p. 1113) to reclaim a dis-

posed acknowledged instance. The least recently disposed instance

will be reclaimed.

DDS ALIVE THEN DISPOSED INSTANCE REPLACEMENT

Allows a DDSDataWriter (p. 1113) ﬁrst to reclaim an alive ac-

know ledged instance, and then if necessary a disposed acknowledged

instance.

When an unregistered acknowledged instance is not available to re-

claim, this kind allows a DDSDataWriter (p.

1113) ﬁrst try reclaim-

ing an alive acknowledged instance. If no instance is reclaimable, then

it trys reclaiming a disposed acknowledged instance. The least recently

used (i.e. registered, written, or disposed) instance will be reclaimed.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

412 Module Documentation

DDS DISPOSED THEN ALIVE INSTANCE REPLACEMENT

Allows a DDSDataWriter (p. 1113) ﬁrst to reclaim a disposed ac-

knowledged instance, and then if necessary an alive acknowledged

instance.

When an unregistered acknowledged instance is not available to re-

claim, this kind allows a DDSDataWriter (p. 1113) ﬁrst try reclaim-

ing a disposed acknowledged instance. If no instance is reclaimable,

then it trys reclaiming an alive acknowledged instance. The least

recently used (i.e. disposed, registered, or written) instance will be

reclaimed.

DDS ALIVE OR DISPOSED INSTANCE REPLACEMENT

Allows a DDSDataWriter (p. 1113) to reclaim a either an alive

acknowledged instance or a disposed acknowledged instance.

When an unregistered acknowledged instance is not available to re-

claim, this kind allows a DDSDataWriter (p. 1113) to reclaim either

an alive acknowledged instance or a disposed acknowledged instance.

If both instance kinds are available to reclaim, the DDSDataWriter

(p. 1113) will reclaim the least recently used (i.e. disp ose d, registered,

or written) instance.

5.120.3 Variable Documentation

5.120.3.1 const char∗ const DDS -

DATAWRITERRESOURCELIMITS -

QOS POLICY NAME

Stringiﬁed human-readable name for DDS -

DataWriterResourceLimitsQosPolicy (p. 560).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.121 DATA READER PROTOCOL 413

5.121 DATA READER PROTOCOL

<<eXtension>> ( p. 199) Speciﬁes the DataReader-speciﬁc protocol QoS.

Classes

struct DDS DataReaderProtocolQosPolicy

Along with DDS WireProtocolQosPolicy ( p. 1059) and DDS -

DataWriterProtocolQosPolicy ( p. 535), this QoS policy conﬁgures

the DDS on-the-network protocol (RTPS).

Variables

const char ∗const DDS DATAREADERPROTOCOL QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS -

DataReaderProtocolQosPolicy ( p. 501).

5.121.1 Detailed Description

<<eXtension>> ( p. 199) Speciﬁes the DataReader-speciﬁc protocol QoS.

5.121.2 Variable Documentation

5.121.2.1 const char∗ const DDS DATAREADERPROTOCOL -

QOS POLICY NAME

Stringiﬁed human-readable name for DDS DataReaderProtocolQosPolicy

(p. 501).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

414 Module Documentation

5.122 DATA WRITER PROTOCOL

<<eXtension>> ( p. 199) Along with DDS WireProtocolQosPolicy

(p. 1059) and DDS DataReaderProtocolQosPolicy (p. 501), this QoS pol-

icy conﬁgures the DDS on-the-network protocol (RTPS).

Classes

struct DDS DataWriterProto colQosPolicy

Protocol that applies only to DDSDataWriter ( p. 1113) instances.

Variables

const char ∗const DDS DATAWRITERPROTOCOL QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS -

DataWriterProtocolQosPolicy ( p. 535).

5.122.1 Detailed Description

<<eXtension>> ( p. 199) Along with DDS WireProtocolQosPolicy

(p. 1059) and DDS DataReaderProtocolQosPolicy (p. 501), this QoS pol-

icy conﬁgures the DDS on-the-network protocol (RTPS).

5.122.2 Variable Documentation

5.122.2.1 const char∗ const DDS DATAWRITERPROTOCOL -

QOS POLICY NAME

Stringiﬁed human-readable name for DDS DataWriterProtocolQosPolicy

(p. 535).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.123 SYSTEM RESOURCE LIMITS 415

5.123 SYSTEM RESOURCE LIMITS

<<eXtension>> ( p. 199) Conﬁgures DomainParticipant-independent re-

sources used by RTI Connext.

Classes

struct DDS SystemResourceLimitsQosPolicy

Conﬁgures DDSDomainParticipant ( p. 1139)-independent resources used

by RTI Connext. Mainly used to change the maximum number of DDS-

DomainParticipant ( p. 1139) entities that can be created within a single

process (address space).

Variables

const char ∗const DDS SYSTEMRESOURCELIMITS QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS -

SystemResourceLimitsQosPolicy ( p. 948).

5.123.1 Detailed Description

<<eXtension>> ( p. 199) Conﬁgures DomainParticipant-independent re-

sources used by RTI Connext.

5.123.2 Variable Documentation

5.123.2.1 const char∗ const DDS SYSTEMRESOURCELIMITS -

QOS POLICY NAME

Stringiﬁed human-readable name for DDS -

SystemResourceLimitsQosPolicy (p. 948).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

416 Module Documentation

5.124 DOMAIN PARTICIPANT -

RESOURCE LIMITS

<<eXtension>> ( p. 199) Various settings that conﬁgure how a DDSDo-

mainParticipant (p. 1139) allocates and uses physical memory for internal

resources, including the maximum sizes of various properties.

Classes

struct DDS AllocationSettings t

Resource allocation settings.

struct DDS DomainParticipantResourceLimitsQosPolicy

Various settings that conﬁgure how a DDSDomainParticipant ( p. 1139)

allocates and uses physical memory for internal resources, including the max-

imum sizes of various properties.

Variables

const char ∗const DDS DOMAINPARTICIPANTRESOURCELIMITS -

QOS POLICY NAME

Stringiﬁed human-readable name for DDS -

DomainParticipantResourceLimitsQosPolicy ( p. 593).

5.124.1 Detailed Description

<<eXtension>> ( p. 199) Various settings that conﬁgure how a DDSDo-

mainParticipant (p. 1139) allocates and uses physical memory for internal

resources, including the maximum sizes of various properties.

5.124.2 Variable Documentation

5.124.2.1 const char∗ const DDS -

DOMAINPARTICIPANTRESOURCELIMITS QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS -

DomainParticipantResourceLimitsQosPolicy (p. 593).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.125 EVENT 417

5.125 EVENT

<<eXtension>> ( p. 199) Conﬁgures the internal thread in a DomainPartici-

pant that handles timed events.

Classes

struct DDS EventQosPolicy

Settings for event.

Variables

const char ∗const DDS EVENT QOS POLICY NAME

Stringiﬁed human-readable name for DDS EventQosPolicy ( p. 739).

5.125.1 Detailed Description

<<eXtension>> ( p. 199) Conﬁgures the internal thread in a DomainPartici-

pant that handles timed events.

5.125.2 Variable Documentation

5.125.2.1 const char∗ const DDS EVENT QOS POLICY NAME

Stringiﬁed human-readable name for DDS EventQosPolicy (p. 739).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

418 Module Documentation

5.126 DATABASE

<<eXtension>> ( p. 199) Various threads and resource limits settings used

by RTI Connext to control its internal database.

Classes

struct DDS DatabaseQosPolicy

Various threads and resource limits settings used by RTI Connext to control

its internal database.

Variables

const char ∗const DDS DATABASE QOS POLICY NAME

Stringiﬁed human-readable name for DDS DatabaseQosPolicy ( p. 495).

5.126.1 Detailed Description

<<eXtension>> ( p. 199) Various threads and resource limits settings used

by RTI Connext to control its internal database.

5.126.2 Variable Documentation

5.126.2.1 const char∗ const DDS DATABASE QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS DatabaseQosPolicy (p. 495).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.127 RECEIVER POOL 419

5.127 RECEIVER POOL

<<eXtension>> ( p. 199) Conﬁgures threads used by RTI Connext to receive

and process data from transports (for example, UDP sockets).

Classes

struct DDS ReceiverPoolQosPolicy

Conﬁgures threads used by RTI Connext to receive and process data from

transports (for example, UDP sockets).

Variables

const char ∗const DDS RECEIVERPOOL QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS ReceiverPoolQosPolicy

( p. 862).

5.127.1 Detailed Description

<<eXtension>> ( p. 199) Conﬁgures threads used by RTI Connext to receive

and process data from transports (for example, UDP sockets).

5.127.2 Variable Documentation

5.127.2.1 const char∗ const DDS RECEIVERPOOL QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS ReceiverPoolQosPolicy (p. 862).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

420 Module Documentation

5.128 PUBLISH MODE

<<eXtension>> ( p. 199) Speciﬁes how RTI Connext sends application data

on the network. This QoS policy can b e used to tell RTI Connext to use its

own thread to send data, instead of the user thread.

Classes

struct DDS PublishModeQosPolicy

Speciﬁes how RTI Connext sends application data on the network. This QoS

policy can be used to tell RTI Connext to use its own thread to send data,

instead of the user thread.

Deﬁnes

#deﬁne DDS PUBLICATION PR IORITY UNDEFINED

Initializer value for DDS PublishModeQosPolicy::priority ( p. 855)

and/or DDS ChannelSettings t::priority ( p. 487).

#deﬁne DDS PUBLICATION PR IORITY AUTOMATIC

Constant value for DDS PublishModeQosPolicy::priority ( p. 855)

and/or DDS ChannelSettings t::priority ( p. 487).

Enumerations

enum DDS PublishModeQosPolicyKind {

DDS SYNCHRONOUS PUBLISH MODE QOS,

DDS ASYNCHRONOUS PUBLISH MODE QOS }

Kinds of publishing mode.

Variables

const char ∗const DDS PUBLISHMODE QOS POLICY NAME

Stringiﬁed human-readable name for DDS PublishModeQosPolicy

( p. 853).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.128 PUBLISH MODE 421

5.128.1 Detailed Description

<<eXtension>> ( p. 199) Speciﬁes how RTI Connext sends application data

on the network. This QoS policy can b e used to tell RTI Connext to use its

own thread to send data, instead of the user thread.

5.128.2 Deﬁne Documentation

5.128.2.1 #deﬁne DDS PUBLICATION PR IORITY -

UNDEFINED

Initializer value for DDS PublishModeQosPolicy::priority (p. 855) and/or

DDS ChannelSettings t::priority (p. 487).

When assigned this value, the publication priority of the data writer, or channel

of a multi-channel data writer, will be set to the lowest possible value. For

muilti-channel data writers, if either the data writer or channel priority is NOT

set to this value, then the publication priority of the entity will be set to the

deﬁned value.

5.128.2.2 #deﬁne DDS PUBLICATION PR IORITY -

AUTOMATIC

Constant value for DDS PublishModeQosPolicy::priority (p. 855) and/or

DDS ChannelSettings t::priority (p. 487).

When assigned this value, the publication priority of the data writer, or chan-

nel of a multi-channel data writer, will be se t to the largest priority value of

any sample currently queued for publication by the data writer or data writer

channel.

5.128.3 Enumeration Type Documentation

5.128.3.1 enum DDS PublishModeQosPolicyKind

Kinds of publishing mode.

QoS:

DDS PublishModeQosPolicy (p. 853)

Enumerator:

DDS SYNCHRONOUS PUBLISH MODE QOS Indicates to send

data synchronously.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

422 Module Documentation

If DDS DataWriterProtocolQosPolicy::push on write (p. 537)

is DDS BOOLEAN TRUE (p. 298), data is sent immediately in

the context of FooDataWriter::write (p. 1484).

As data is sent immediately in the context of the user thread, no ﬂow

control is applied.

See also:

DDS DataWriterProtocolQosPolicy::push on write

(p. 537)

[default] for DDSDataWriter (p. 1113)

DDS ASYNCHRONOUS PUBLISH MODE QOS Indicates to

send data asynchronously.

Conﬁgures the DDSDataWriter (p. 1113) to delegate the task

of data transmission to a separate publishing thread. The Foo-

DataWriter::write (p. 1484) call does not send the data, but instead

schedules the data to be sent later by its associated DDSPublisher

(p. 1346).

Each DDSPublisher (p. 1346) uses its dedicated publishing thread

(DDS PublisherQos::asynchronous publisher (p. 852)) to send

data for all its asynchronous DataWriters. For each asynchronous

DataWriter, the associated DDSFlowController (p. 1259) deter-

mines when the publishing thread is allowed to send the data.

DDSDataWriter::wait for asynchronous publishing (p. 1126)

and DDSPublisher::wait for asynchronous publishing

(p. 1365) enable you to determine when the data has actually

been sent.

See also:

DDSFlowController (p. 1259)

DDS HistoryQosPolicy (p. 758)

DDSDataWriter::wait for asynchronous publishing

(p. 1126)

DDSPublisher::wait for asynchronous publishing

(p. 1365)

NDDS Transport Property t::gather send buﬀer count -

max (p. 1525)

5.128.4 Variable Documentation

5.128.4.1 const char∗ const DDS PUBLISHMODE QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS PublishModeQosPolicy (p. 853).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.129 DISCOVERY CONFIG 423

5.129 DISCOVERY CONFIG

<<eXtension>> ( p. 199) Speciﬁes the discovery conﬁguration QoS.

Classes

struct DDS BuiltinTopicReaderResourceLimits t

Built-in topic reader’s resource limits.

struct DDS DiscoveryConﬁgQosPolicy

Settings for discovery conﬁguration.

Deﬁnes

#deﬁne DDS DISCOVERYCONFIG BUILTIN PLUGIN -

MASK ALL

All bits are set.

#deﬁne DDS DISCOVERYCONFIG BUILTIN PLUGIN -

MASK NONE

No bits are set.

#deﬁne DDS DISCOVERYCONFIG -

BUILTIN PLUGIN MASK DEFAULT (DDS -

DiscoveryConﬁgBuiltinPluginKindMask)DDS -

DISCOVERYCONFIG BUILTIN SDP

The default value of DDS DiscoveryConﬁgQosPolicy::builtin -

discovery plugins ( p. 580).

Typedefs

typedef DDS Long DDS DiscoveryConﬁgBuiltinPluginKindMask

A bit-mask (list) of built-in discove ry plugins.

Enumerations

enum DDS DiscoveryConﬁgBuiltinPluginKind { , DDS -

DISCOVERYCONFIG BUILTIN SDP }

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

424 Module Documentation

Built-in discovery plugins that can be used.

enum DDS RemoteParticipantPurgeKind {

DDS LIVELINESS BASED REMOTE PARTICIPANT -

PURGE,

DDS NO REMOTE PARTICIPANT PURGE }

Available behaviors for halting communication with remote participants (and

their contained entities) with which discovery communication has been lost.

Variables

const char ∗const DDS DISCOVERYCONFIG QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS DiscoveryConﬁgQosPolicy

( p. 573).

5.129.1 Detailed Description

<<eXtension>> ( p. 199) Speciﬁes the discovery conﬁguration QoS.

5.129.2 Deﬁne Documentation

5.129.2.1 #deﬁne DDS DISCOVERYCONFIG BUILTIN -

PLUGIN MASK ALL

All bits are set.

See also:

DDS DiscoveryConﬁgBuiltinPluginKindMask (p. 425)

5.129.2.2 #deﬁne DDS DISCOVERYCONFIG BUILTIN -

PLUGIN MASK NONE

No bits are set.

See also:

DDS DiscoveryConﬁgBuiltinPluginKindMask (p. 425)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.129 DISCOVERY CONFIG 425

5.129.2.3 #deﬁne DDS DISCOVERYCONFIG -

BUILTIN PLUGIN MASK DEFAULT (DDS -

DiscoveryConﬁgBuiltinPluginKindMask)DDS -

DISCOVERYCONFIG BUILTIN SDP

The default value of DDS DiscoveryConﬁgQosPolicy::builtin -

discovery plugins (p. 580).

See also:

DDS DiscoveryConﬁgBuiltinPluginKindMask (p. 425)

5.129.3 Typedef Documentation

5.129.3.1 typedef DDS Long DDS -

DiscoveryConﬁgBuiltinPluginKindMask

A bit-mask (list) of built-in discovery plugins.

The bit-mask is an eﬃcient and compact representation of a ﬁxed-length list of

DDS DiscoveryConﬁgBuiltinPluginKind (p. 425) values .

QoS:

DDS DiscoveryConﬁgQosPolicy (p. 573)

5.129.4 Enumeration Type Documentation

5.129.4.1 enum DDS DiscoveryConﬁgBuiltinPluginKind

Built-in discovery plugins that can be used.

See also:

DDS DiscoveryConﬁgBuiltinPluginKindMask (p. 425)

Enumerator:

DDS DISCOVERYCONFIG BUILTIN SDP [default] Simple dis-

covery plugin.

5.129.4.2 enum DDS RemoteParticipantPurgeKind

Available behaviors for halting communication with remote participants (and

their contained entities) with which discovery communication has been lost.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

426 Module Documentation

When discovery communication with a remote participant has been lost, the

local participant must make a decision about whether to continue attempting

to c ommunicate with that participant and its contained entities. This ”kind” is

used to select the desired behavior.

This ”kind” does not pertain to the situation in which a remote participant has

been gracefully deleted and notiﬁcation of that deletion have been successfully

received by its peers. In that case, the local participant will immediately stop

attempting to communicate with those entities and will remove the associated

remote entity records from its internal database.

See also:

DDS DiscoveryConﬁgQosPolicy::remote participant purge kind

(p. 576)

Enumerator:

DDS LIVELINESS BASED REMOTE PARTICIPANT PURGE

[default] Maintain knowledge of the remote participant for as long

as it maintains its liveliness contract.

A participant will continue attempting communication with its peers,

even if discovery communication with them is lost, as long as the re-

mote participants maintain their liveliness. If both discovery commu-

nication and participant liveliness are lost, however, the local partici-

pant will remove all records of the remote participant and its contained

endpoints, and no further data communication with them will occur

until and unless they are rediscovered.

The liveliness contract a participant promises to its peers –

its ”liveliness lease duration” – is speciﬁed in its DDS -

DiscoveryConﬁgQosPolicy::participant liveliness lease -

duration (p. 575) QoS ﬁeld. It maintains that contract by writing

data to those other participants with a writer that has a DDS -

LivelinessQosPolicyKind (p. 358) of DDS AUTOMATIC -

LIVELINESS QOS (p. 359) or DDS MANUAL BY -

PARTICIPANT LIVELINESS QOS (p. 359) and by asserting

itself (at the DDS DiscoveryConﬁgQosPolicy::participant -

liveliness assert period (p. 576)) over the Simple Discovery

Protocol.

DDS NO REMOTE PARTICIPANT PURGE Never ”forget” a

remote participant with which discovery communication has bee n lost.

If a participant with this behavior loses discovery communication with

a remote participant, it will nevertheless remember that remote par-

ticipant and its endpoints and continue attempting to communicate

with them indeﬁnitely.

This value has consequences for a participant’s resource usage. If

discovery communication with a remote participant is lost, but the

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.129 DISCOVERY CONFIG 427

same participant is later rediscovered, any relevant records that remain

in the database will be reused. However, if it is not rediscovered, the

records will continue to take up space in the database for as long as

the local participant remains in existence.

5.129.5 Variable Documentation

5.129.5.1 const char∗ const DDS DISCOVERYCONFIG QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS DiscoveryConﬁgQosPolicy

(p. 573).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

428 Module Documentation

5.130 ASYNCHRONOUS PUBLISHER

<<eXtension>> ( p. 199) Speciﬁes the asynchronous publishing settings of

the DDSPublisher (p. 1346) instances.

Classes

struct DDS AsynchronousPublisherQosPolicy

Conﬁgures the mechanism that sends user data in an external middleware

thread.

Variables

const char ∗const DDS ASYNCHRONOUSPUBLISHER QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS -

AsynchronousPublisherQosPolicy ( p. 466).

5.130.1 Detailed Description

<<eXtension>> ( p. 199) Speciﬁes the asynchronous publishing settings of

the DDSPublisher (p. 1346) instances.

5.130.2 Variable Documentation

5.130.2.1 const char∗ const DDS -

ASYNCHRONOUSPUBLISHER QOS POLICY NAME

Stringiﬁed human-readable name for DDS -

AsynchronousPublisherQosPolicy (p. 466).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.131 TYPESUPPORT 429

5.131 TYPESUPPORT

<<eXtension>> ( p. 199) Allows you to attach application-speciﬁc values to a

DataWriter or DataReader that are passed to the serialization or deserialization

routine of the associated data type.

Classes

struct DDS TypeSupportQosPolicy

Allows you to attach application-speciﬁc values to a DataWriter or

DataReader that are passed to the serialization or deserialization routine

of the associated data type.

Variables

const char ∗const DDS TYPESUPPORT QOS POLICY NAME

Stringiﬁed human-readable name for DDS TypeSupportQosPolicy

( p. 1040).

5.131.1 Detailed Description

<<eXtension>> ( p. 199) Allows you to attach application-speciﬁc values to a

DataWriter or DataReader that are passed to the serialization or deserialization

routine of the associated data type.

5.131.2 Variable Documentation

5.131.2.1 const char∗ const DDS TYPESUPPORT QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS TypeSupportQosPolicy

(p. 1040).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

430 Module Documentation

5.132 EXCLUSIVE AREA

<<eXtension>> ( p. 199) Conﬁgures multi-thread concurrency and deadlock

prevention c apabilities.

Classes

struct DDS ExclusiveAreaQosPol icy

Conﬁgures multi-thread concurrency and deadlock prevention capabilities.

Variables

const char ∗const DDS EXCLUSIVEAREA QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS ExclusiveAreaQosPolicy

( p. 742).

5.132.1 Detailed Description

<<eXtension>> ( p. 199) Conﬁgures multi-thread concurrency and deadlock

prevention c apabilities.

5.132.2 Variable Documentation

5.132.2.1 const char∗ const DDS EXCLUSIVEAREA QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS ExclusiveAreaQosPolicy

(p. 742).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.133 BATCH 431

5.133 BATCH

<<eXtension>> ( p. 199) Batch QoS policy used to enable batching in DDS-

DataWriter (p. 1113) instances.

Classes

struct DDS BatchQosPolicy

Used to conﬁgure batching of multiple samples into a single network packet

in order to increase throughput for small samples.

Variables

const char ∗const DDS BATCH QOS POLICY NAME

Stringiﬁed human-readable name for DDS BatchQosPolicy ( p. 476).

5.133.1 Detailed Description

<<eXtension>> ( p. 199) Batch QoS policy used to enable batching in DDS-

DataWriter (p. 1113) instances.

5.133.2 Variable Documentation

5.133.2.1 const char∗ const DDS BATCH QOS POLICY NAME

Stringiﬁed human-readable name for DDS BatchQosPolicy (p. 476).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

432 Module Documentation

5.134 TYPE CONSISTENCY -

ENFORCEMENT

Deﬁnes the rules for determining whether the type used to publish a given topic

is consistent with that used to subscribe to it.

Classes

struct DDS TypeConsistencyEnforcementQosPolicy

Deﬁnes the rules for determining whether the type used to publish a given

topic is consistent with that used to subscribe to it.

Enumerations

enum DDS TypeConsistencyKind {

DDS DISALLOW TYPE COERCION,

DDS ALLOW TYPE COERCION }

Kinds of type consistency.

Variables

const char ∗const DDS TYPE CONSISTENCY -

ENFORCEMENT QOS POLICY NAME

Stringiﬁed human-readable name for DDS -

TypeConsistencyEnforcementQosPolicy ( p. 1038).

5.134.1 Detailed Description

Deﬁnes the rules for determining whether the type used to publish a given topic

is consistent with that used to subscribe to it.

5.134.2 Enumeration Type Documentation

5.134.2.1 enum DDS TypeConsistencyKind

Kinds of type consistency.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.134 TYPE CONSISTENCY ENFORCEMENT 433

QoS:

DDS TypeConsistencyEnforcementQosPolicy (p. 1038)

Enumerator:

DDS DISALLOW TYPE COERCION The DataWriter and the

DataReader must support the same data type in order for them to

communicate.

This is the degree of type consistency enforcement required by the

OMG DDS Specification prior to the OMG Extensible and Dynamic

Topic Types for DDS Specification.

DDS ALLOW TYPE COERCION The DataWriter and the

DataReader need not support the same data type in order for them

to communicate as long as the DataReaders type is assignable from

the DataWriters type.

For example, the following two extensible types will be assignable to

each other since MyDerivedType contains all the members of MyBase-

Type (member 1) plus some additional elements (member 2).

struct MyBaseType {

long member_1;

};

struct MyDerivedType: MyBaseType {

long member_2;

};

Even if MyDerivedType was not explicitly inheriting from MyBase-

Type the types would still be assignable. For example:

struct MyBaseType {

long member_1;

};

struct MyDerivedType {

long member_1;

long member_2;

};

For additional information on type assignability refer to the OMG

Extensible and Dynamic Topic Types for DDS Specification.

[default]

5.134.3 Variable Documentation

5.134.3.1 const char∗ const DDS TYPE CONSISTENCY -

ENFORCEMENT QOS POLICY NAME

Stringiﬁed human-readable name for DDS -

TypeConsistencyEnforcementQosPolicy (p. 1038).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

434 Module Documentation

5.135 LOCATORFILTER

<<eXtension>> ( p. 199) The QoS policy used to report the conﬁguration of

a MultiChannel DataWriter as part of DDS PublicationBuilti nTopicData

(p. 839).

Classes

struct DDS LocatorFilter t

Speciﬁes the conﬁguration of an individual channel within a MultiChannel

DataWriter.

struct DDS LocatorFilterSeq

Declares IDL sequence< DDS LocatorFilter t ( p. 785) >.

struct DDS LocatorFilterQosPolicy

The QoS policy used to report the conﬁguration of a MultiChannel

DataWriter as part of DDS PublicationBuiltinTopicData ( p. 839).

Variables

const char ∗const DDS LOCATORFILTER QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS LocatorFilterQosPolicy

( p. 787).

5.135.1 Detailed Description

<<eXtension>> ( p. 199) The QoS policy used to report the conﬁguration of

a MultiChannel DataWriter as part of DDS PublicationBuilti nTopicData

(p. 839).

5.135.2 Variable Documentation

5.135.2.1 const char∗ const DDS LOCATORFILTER QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS LocatorFilterQosPolicy (p. 787).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.136 MULTICHANNEL 435

5.136 MULTICHANNEL

<<eXtension>> ( p. 199) Conﬁgures the ability of a DataWriter to send data

on diﬀerent multicast groups (addresses) based on the value of the data.

Classes

struct DDS ChannelSettings t

Type used to conﬁgure the properties of a channel.

struct DDS ChannelSettingsSeq

Declares IDL sequence< DDS ChannelSettings t ( p. 486) >.

struct DDS MultiChannelQosPolicy

Conﬁgures the ability of a DataWriter to send data on diﬀerent multicast

groups (addresses) based on the value of the data.

Variables

const char ∗const DDS MULTICHANNEL QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS MultiChannelQosPolicy

( p. 796).

5.136.1 Detailed Description

<<eXtension>> ( p. 199) Conﬁgures the ability of a DataWriter to send data

on diﬀerent multicast groups (addresses) based on the value of the data.

5.136.2 Variable Documentation

5.136.2.1 const char∗ const DDS MULTICHANNEL QOS -

POLICY NAME

Stringiﬁed human-readable name for DDS MultiChannelQosPolicy (p. 796).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

436 Module Documentation

5.137 PROPERTY

<<eXtension>> ( p. 199) Stores name/value (string) pairs that can be used

to conﬁgure certain parameters of RTI Connext that are not exposed through

formal QoS policies. Can also be used to store and propagate application-speciﬁc

name/value pairs that can be retrieved by user code during discovery.

Classes

class DDSPropertyQosPolicyHelper

Policy Helpers which facilitate management of the properties in the input

policy.

struct DDS Property t

Properties are name/value pairs objects.

struct DDS PropertySeq

Declares IDL sequence < DDS Property t ( p. 833) >.

struct DDS PropertyQosPolicy

Stores name/value(string) pairs that can be used to conﬁgure certain param-

eters of RTI Connext that are not exposed through formal QoS policies. Can

also be used to store and propagate application-speciﬁc name/value pairs that

can be retrieved by user code during discovery.

Functions

static DDS Long DDSPropertyQosPolicyHel per::get number -

of properties (DDS PropertyQosPolicy &policy)

Gets the number of properties in the input policy.

static DDS ReturnCode t DDSPropertyQosPolicy-

Helper::assert property (DDS PropertyQosPolicy &policy, c onst

char ∗name, const char ∗value, DDS Boolean propagate)

Asserts the property identiﬁed by name in the input policy.

static DDS ReturnCode t DDSPropertyQosPolicyHelper::add -

property (DDS PropertyQosPolicy &policy, const char ∗name, const

char ∗value, DDS Boolean propagate)

Adds a new property to the input policy.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.137 PROPERTY 437

static struct DDS Property t ∗ DDSPropertyQosPolicy-

Helper::lookup property (DDS PropertyQosPolicy &policy,

const char ∗name)

Searches for a property in the input policy given its name.

static DDS ReturnCode t DDSPropertyQosPolicy-

Helper::remove property (DDS PropertyQosPolicy &policy,

const char ∗name)

Removes a property from the input policy.

static DDS ReturnCode t DDSPropertyQosPolicyHelper::get -

properties (DDS PropertyQosPolicy &policy, struct DDS -

PropertySeq &properties, const char ∗name preﬁx)

Retrieves a list of properties whose names match the input preﬁx.

Variables

const char ∗const DDS PROPERTY QOS POLICY NAME

Stringiﬁed human-readable name for DDS PropertyQosPolicy ( p. 834).

5.137.1 Detailed Description

<<eXtension>> ( p. 199) Stores name/value (string) pairs that can be used

to conﬁgure certain parameters of RTI Connext that are not exposed through

formal QoS policies. Can also be used to store and propagate application-speciﬁc

name/value pairs that can be retrieved by user code during discovery.

RTI Connext will automatically set some system properties in

the DDS PropertyQosPolicy (p. 834) associated with a DDS -

DomainParticipantQos (p. 588). See System Properties (p. 150) for

additional details.

5.137.2 Function Documentation

5.137.2.1 static DDS Long DDSPropertyQosPolicyHel per::get -

number of properties (DDS PropertyQosPolicy & policy)

[static, inherited]

Gets the number of properties in the input policy.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

438 Module Documentation

Precondition:

policy cannot be NULL.

Parameters:

policy <<in>> ( p. 200) Input policy.

Returns:

Number of properties.

5.137.2.2 static DDS ReturnCode t DDSPropertyQosPolicy-

Helper::assert property (DDS PropertyQosPolicy

& policy, const char ∗ name, const char ∗ value,

DDS Boolean propagate) [static, inherited]

Asserts the property identiﬁed by name in the input policy.

If the property already exists, this function replaces its current value with the

new one.

If the property identiﬁed by name does not exist, this function adds it to the

property set.

This function increases the maximum number of elements of the policy sequence

when this number is not enough to store the new property.

Precondition:

policy, name and value cannot be NULL.

Parameters:

policy <<in>> ( p. 200) Input policy.

name <<in>> ( p. 200) Property name.

value <<in>> ( p. 200) Property value.

propagate <<in>> ( p. 200) Indicates if the property will be propagated

on discovery.

Returns:

One of the Standard Return Codes (p. 314) or DDS RETCODE -

OUT OF RESOURCES (p. 315).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.137 PROPERTY 439

5.137.2.3 static DDS ReturnCo de t DDSPropertyQosPolicy-

Helper::add property (DDS PropertyQosPolicy & policy,

const char ∗ name, const char ∗ value, DDS Boolean

propagate) [static, inherited]

Adds a new property to the input policy.

This function will allocate memory to store the (name,value) pair. The memory

allocated is owned by RTI Connext.

If the maximum number of elements of the policy sequence is not enough to

store the new property, this function will increase it.

If the property already exists the function fails with DDS RETCODE -

PRECONDITION NOT MET (p. 315).

Precondition:

policy, name and value cannot be NULL.

The property is not in the policy.

Parameters:

policy <<in>> ( p. 200) Input policy.

name <<in>> ( p. 200) Property name.

value <<in>> ( p. 200) Property value.

propagate <<in>> ( p. 200) Indicates if the property will be propagated

on discovery.

Returns:

One of the Standard Return Codes (p. 314) or DDS -

RETCODE OUT OF RESOURCES (p. 315) or DDS RETCODE -

PRECONDITION NOT MET (p. 315)

5.137.2.4 static struct DDS Property t∗

DDSPropertyQosPolicyHelper::lookup property

(DDS PropertyQosPoli cy & policy, const char ∗ name)

[static, read, inherited]

Searches for a property in the input policy given its name.

Precondition:

policy, name and value cannot be NULL.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

440 Module Documentation

Parameters:

policy <<in>> ( p. 200) Input policy.

name <<in>> ( p. 200) Property name.

Returns:

On success, the function returns the ﬁrst property with the given name.

Otherwise, the function returns NULL.

5.137.2.5 static DDS ReturnCode t DDSPropertyQosPolicy-

Helper::remove property (DDS PropertyQosPolicy &

policy, const char ∗ name) [static, inherited]

Removes a property from the input policy.

If the property does not exist, the function fails with DDS RETCODE -

PRECONDITION NOT MET (p. 315).

Precondition:

policy and name cannot be NULL.

The property is in the policy.

Parameters:

policy <<in>> ( p. 200) Input policy.

name <<in>> ( p. 200) Property name.

Returns:

One of the Standard Return Codes (p. 314) or DDS RETCODE -

PRECONDITION NOT MET (p. 315).

5.137.2.6 static DDS

ReturnCode t DDSPropertyQosPolicy-

Helper::get properties (DDS PropertyQosPolicy &

policy, struct DDS PropertySeq & properties, const

char ∗ name preﬁx) [static, inherited]

Retrieves a list of properties whose names match the input preﬁx.

If the properties sequence doesn’t own its buﬀer, and its maximum is less

than the total number of properties matching the input preﬁx, it will be ﬁlled

up to its maximum and fail with an error of DDS RETCODE OUT OF -

RESOURCES (p. 315).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.137 PROPERTY 441

Precondition:

policy, properties and name preﬁx cannot be NULL.

Parameters:

policy <<in>> ( p. 200) Input policy.

properties <<inout>> ( p. 200) A DDS PropertySeq (p. 837) object

where the set or list of properties will be returned.

name preﬁx Name preﬁx.

Returns:

One of the Standard Return Codes (p. 314) or DDS RETCODE -

OUT OF RESOURCES (p. 315).

5.137.3 Variable Documentation

5.137.3.1 const char∗ const DDS PROPERTY QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS PropertyQosPolicy (p. 834).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

442 Module Documentation

5.138 AVAILABILITY

<<eXtension>> ( p. 199) Conﬁgures the availability of data.

Classes

struct DDS EndpointGroup t

Speciﬁes a group of endpoints that can be collectively identiﬁed by a name

and satisﬁed by a quorum.

struct DDS EndpointGroupSeq

A sequence of DDS EndpointGroup t ( p. 731).

struct DDS AvailabilityQosPolicy

Conﬁgures the availability of data.

Variables

const char ∗const DDS AVAILABILITY QOS POLICY NAME

Stringiﬁed human-readable name for DDS AvailabilityQosPolicy

( p. 471).

5.138.1 Detailed Description

<<eXtension>> ( p. 199) Conﬁgures the availability of data.

5.138.2 Variable Documentation

5.138.2.1 const char∗ const DDS AVAILABILITY QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS AvailabilityQosPolicy (p. 471).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.139 Entity Support 443

5.139 Entity Support

DDSEntity (p. 1253), DDSListener (p. 1318) and related items.

Classes

class DDSListener

<<inter face>> (p. 199) Abstract base class for all Listener interfaces.

class DDSEntity

<<inter face>> (p. 199) Abstract base class for all the DDS objects that

support QoS policies, a listener, and a status condition.

class DDSDomainEntity

<<inter face>> (p. 199) Abstract base class for all DDS entities except for

the DDSDomainParticipant ( p. 1139).

5.139.1 Detailed Description

DDSEntity (p. 1253), DDSListener (p. 1318) and related items.

DDSEntity (p. 1253) subtypes are created and destroyed by factory objects.

With the exception of DDSDomainParticipant (p. 1139), whose factory is

DDSDomainParticipantFactory (p. 1216), all DDSEntity (p. 1253) factory

objects are themselves DDSEntity (p. 1253) subtypes as well.

Important: all DDSEntity (p. 1253) delete operations are inherently thread-

unsafe. The user must take extreme care that a given DDSEntity (p. 1253)

is not destroyed in one thread while being used concurrently (including being

deleted concurrently) in another thread. An operation’s eﬀect in the presence

of the concurrent deletion of the operation’s target DDSEntity (p. 1253) is

undeﬁned.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

444 Module Documentation

5.140 Conditions and WaitSets

DDSCondition (p. 1075) and DDSWaitSet (p. 1433) and related items.

Classes

struct DDSConditionSeq

Instantiates FooSeq (p. 1494) < DDSCondition ( p. 1075) >.

class DDSCondition

<<inter face>> (p. 199) Root class for all the conditions that may be at-

tached to a DDSWaitSet ( p. 1433).

class DDSGuardCondition

<<inter face>> (p. 199) A speciﬁc DDSCondition ( p. 1075) whose

trigger value is completely under the control of the application.

class DDSStatusCondition

<<inter face>> (p. 199) A speciﬁc DDSCondition ( p. 1075) that is asso-

ciated with each DDSEntity ( p. 1253).

class DDSWaitSet

<<inter face>> (p. 199) Allows an application to wait until one or more

of the attached DDSCondition ( p. 1075) objects has a trigger value of

DDS BOOLEAN TRUE ( p. 298) or else until the timeout expires.

struct DDS WaitSetProp erty t

<<eXtension>> (p. 199) Speciﬁes the DDSWaitSet ( p. 1433) behavior

for multiple trigger events.

5.140.1 Detailed Description

DDSCondition (p. 1075) and DDSWaitSet (p. 1433) and related items.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.141 ENTITY NAME 445

5.141 ENTITY NAME

<<eXtension>> ( p. 199 ) Assigns a name to a DDSDomainParticipant

(p. 1139). This name will be visible during the discovery process and in RTI

tools to help you visualize and debug your system.

Classes

struct DDS EntityNameQosPolicy

Assigns a name and a role name to a DDSDomainParticipant ( p. 1139),

DDSDataWriter ( p. 1113) or DDSDataReader ( p. 1087). These names

will be visible during the discovery process and in RTI tools to help you

visualize and debug your system.

Variables

const char ∗const DDS ENTITYNAME QOS POLICY NAME

Stringiﬁed human-readable name for DDS EntityNameQosPolicy

( p. 735).

5.141.1 Detailed Description

<<eXtension>> ( p. 199 ) Assigns a name to a DDSDomainParticipant

(p. 1139). This name will be visible during the discovery process and in RTI

tools to help you visualize and debug your system.

5.141.2 Variable Documentation

5.141.2.1 const char∗ const DDS ENTITYNAME QOS POLICY -

NAME

Stringiﬁed human-readable name for DDS EntityNameQosPolicy (p. 735).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

446 Module Documentation

5.142 PROFILE

<<eXtension>> ( p. 199) Conﬁgures the way that XML documents contain-

ing QoS proﬁles are loaded by RTI Connext.

Classes

struct DDS ProﬁleQosPolicy

Conﬁgures the way that XML documents containing QoS proﬁles are loaded

by RTI Connext.

Variables

const char ∗const DDS PROFILE QOS POLICY NAME

Stringiﬁed human-readable name for DDS ProﬁleQosPolicy ( p. 830).

5.142.1 Detailed Description

<<eXtension>> ( p. 199) Conﬁgures the way that XML documents contain-

ing QoS proﬁles are loaded by RTI Connext.

5.142.2 Variable Documentation

5.142.2.1 const char∗ const DDS PROFILE QOS POLICY NAME

Stringiﬁed human-readable name for DDS ProﬁleQosPolicy (p. 830).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.143 WriteParams 447

5.143 WriteParams

<<eXtension>> ( p. 199)

Classes

struct DDS SampleIdentity t

Type deﬁnition for an Sample Identity.

struct DDS AckResponseData t

Data payload of an application-level acknowledgment.

struct DDS WriteParams t

<<eXtension>> (p. 199) Input parameters for writing with Foo-

DataWriter::write w params ( p. 1487), FooDataWriter::dispose -

w params ( p. 1491), FooDataWriter::register instance w param s

( p. 1480), FooDataWriter::unregister instance w params ( p. 1483)

Functions

DDS Boolean DDS SampleIdentity equals (const struct DDS -

SampleIdentity t ∗self, const struct DDS Sample Identity t

∗other)

Compares this sample identity with another sample identity for equality.

void DDS WriteParams reset (struct DDS WriteParams t ∗self)

Resets all the ﬁe lds to their default values.

Variables

struct DDS GUID t DDS SampleIdentity t::writer guid

16-byte identiﬁer identifying the virtual GUID.

struct DDS SequenceNumber t DDS SampleIdentity -

t::sequence number

monotonically increasing 64-bit integer that identiﬁes the sample in the data

source.

struct DDS SampleIdentity t DDS AUTO SAMPLE -

IDENTITY

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

448 Module Documentation

The AUTO sample identity.

struct DDS SampleIdent ity t DDS UNKNOWN SAMPLE -

IDENTITY

An invalid or unknown sample identity.

struct DDS WriteParams t DDS WRITEPARAMS DEFAULT

Initializer for DDS WriteParams t ( p. 1067).

5.143.1 Detailed Description

<<eXtension>> ( p. 199)

5.143.2 Function Documentation

5.143.2.1 DDS Boolean DDS SampleIdentity equals (const

struct DDS SampleI dentity t ∗ self, const struct

DDS SampleIdentity t ∗ other)

Compares this sample identity with another sample identity for equality.

Parameters:

self <<in>> ( p. 200) This sample identity.

other <<in>> ( p. 200) The other sample identity to be compared with

this sample identity.

Returns:

DDS BOOLEAN TRUE (p. 298) if the two sample identities have equal

values, or DDS BOOLEAN FALSE (p. 299) otherwise.

5.143.2.2 void DDS WriteParams reset (struct

DDS WriteParams t ∗ self)

Resets all the ﬁelds to their default values.

This operation is useful to reset all the ﬁelds to their automatic value

when DDS WriteParams t::replace auto (p. 1067) is enabled and the same

params instance is used in multiple calls to FooDataWriter::write w params

(p. 1487)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.143 WriteParams 449

5.143.3 Variable Documentation

5.143.3.1 struct DDS GUID t DDS SampleIdentity t::writer guid

[read, inherited]

16-byte identiﬁer identifying the virtual GUID.

5.143.3.2 struct DDS SequenceNumber t DDS -

SampleIdentity t::sequence number [read,

inherited]

monotonically increasing 64-bit integer that identiﬁes the sample in the data

source.

5.143.3.3 struct DDS SampleIdent ity t DDS AUTO SAMPLE -

IDENTITY

The AUTO sample identity.

Special DDS AUTO SAMPLE IDENTITY (p. 449) value {DDS GUID -

AUTO (p. 309), DDS AUTO SEQUENCE NUMBER (p. 311)}

5.143.3.4 struct DDS

SampleIdentity t DDS UNKNOWN -

SAMPLE IDENTITY

An invalid or unknown sample identity.

Special DDS UNKNOWN SAMPLE IDENTITY (p. 449) value

{DDS GUID UNKNOWN (p. 309), DDS SEQUENCE NUMBER -

UNKNOWN (p. 310)}

5.143.3.5 struct DDS WriteParams t DDS WRITEPARAMS -

DEFAULT

Initializer for DDS WriteParams t (p. 1067).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

450 Module Documentation

5.144 LOGGING

<<eXtension>> ( p. 199) Conﬁgures the RTI Connext logging facility.

Classes

struct DDS LoggingQosPolicy

Conﬁgures the RTI Connext logging facility.

Variables

const char ∗const DDS LOGGING QOS POLICY NAME

Stringiﬁed human-readable name for DDS LoggingQosPolicy ( p. 791).

5.144.1 Detailed Description

<<eXtension>> ( p. 199) Conﬁgures the RTI Connext logging facility.

5.144.2 Variable Documentation

5.144.2.1 const char∗ const DDS LOGGING QOS POLICY NAME

Stringiﬁed human-readable name for DDS LoggingQosPolicy (p. 791).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.145 Octet Buﬀer Support 451

5.145 Octet Buﬀer Support

<<eXtension>> ( p. 199) Octet buﬀer creation, cloning, and deletion.

Functions

unsigned char ∗ DDS OctetBuﬀer alloc (unsigned int size)

Create a new empty OctetBuﬀer that can hold up to size octets.

unsigned char ∗ DDS OctetBuﬀer dup (const unsigned char ∗buﬀer,

unsigned int size)

Clone an OctetBuﬀer.

void DDS OctetBuﬀer free (unsigned char ∗buﬀer)

Delete an OctetBuﬀer.

5.145.1 Detailed Description

<<eXtension>> ( p. 199) Octet buﬀer creation, cloning, and deletion.

The methods in this class ensure consistent cross-platform implementa-

tions for OctetBuﬀer creation (DDS OctetBuﬀer alloc() (p. 453)), deletion

(DDS OctetBuﬀer free() (p. 453)), and cloning (DDS OctetBuﬀer dup()

(p. 453)) that preserve the mutable value type semantics. These are to be viewed

as methods that deﬁne an OctetBuffer class whose data is represented by a

’unsigned char∗’.

5.145.2 Conventions

The following conventions govern the memory management of OctetBuﬀers in

RTI Connext.

The DDS implementation ensures that when value types containing Octet-

Buﬀers are passed back and forth to the DDS APIs, the OctetBuﬀers are

created/deleted/cloned using the OctetBuffer class methods.

– Value types containing OctetBuﬀers have ownership of the contained

OctetBuﬀer. Thus, when a value type is deleted, the contained octet

buﬀer ﬁeld is also deleted.

The user must ensure that when value types containing OctetBuﬀers

are passed back and forth to the DDS APIs, the OctetBuﬀers are cre-

ated/deleted/cloned using the OctetBuﬀer class methods.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

452 Module Documentation

The representation of an OctetBuﬀer in C/C++ unfortunately does not allow

programs to detect how much memory has been allocated for a OctetBuﬀer.

RTI Connext must therefore make some assumptions when a user requests that

a OctetBuﬀer be copied into. The following rules apply when RTI Connext is

copying into an OctetBuﬀer.

If the ’unsigned char∗’ is NULL, RTI Connext will allocate a new Octet-

Buﬀer on behalf of the user. To avoid leaking memory, you must ensure

that the OctetBuﬀer will be freed (see Usage ( p. 452) below) in C. For

C++, the destructor of the valuetype containing the OctetBuﬀer will free

it automatically..

If the ’unsigned char∗’ is not NULL, RTI Connext will assume that you are

managing the OctetBuﬀer’s memory yourself and have allocated enough

memory to store the OctetBuﬀer to be copied. RTI Connext will copy into

your memory; to avoid memory corruption, be sure to allocate enough of

it. Also, do not pass structures containing junk pointers into RTI Connext;

you are likely to crash.

5.145.3 Usage

This requirement can generally be assured by adhering to the following idiom

for manipulating OctetBuﬀers.

Always use

DDS_OctetBuffer_alloc() to create,

DDS_OctetBuffer_dup() to clone,

DDS_OctetBuffer_free() to delete

a ’unsigned char*’ that i s passed back and forth between

user code and the DDS C/C++ APIs.

Not adhering to this idiom can result in bad pointers, and incorrect memory

being freed.

In addition, the user code should be vigilant to avoid memory leaks. It is good

practice to:

Balance occurrences of DDS OctetBuﬀer all oc() (p. 453), with match-

ing occurrences of DDS OctetBuﬀer free() (p. 453) in the code.

Finalize value types containing OctetBuﬀer. In C++ the destructor ac-

complishes this automatically. in C, explicit ”destructor” functions are

provided.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.145 Octet Buﬀer Support 453

5.145.4 Function Documentation

5.145.4.1 unsigned char∗ DDS OctetBuﬀer alloc (unsigned int size)

Create a new empty OctetBuﬀer that can hold up to size octets.

An OctetBuﬀer created by this method must be deleted using DDS -

OctetBuﬀer free() (p. 453).

This function will allocate enough memory to hold an OctetBuﬀer of size octets.

Parameters:

size <<in>> ( p. 200) Size of the buﬀer.

Returns:

A newly created non-NULL OctetBuﬀer upon success or NULL upon fail-

ure.

5.145.4.2 unsigned char∗ DDS OctetBuﬀer dup (const unsigned

char ∗ buﬀer, unsigned int size)

Clone an OctetBuﬀer.

An OctetBuﬀer created by this method must be deleted using DDS -

OctetBuﬀer free() (p. 453)

Parameters:

buﬀer <<in>> ( p. 200) The Oc tetBuﬀer to duplicate.

size <<in>> ( p. 200) Size of the OctetBuﬀer to duplicate.

Returns:

If src == NULL or size <0, this method always returns NULL. Otherwise,

upon success it returns a newly created OctetBuﬀer whose value is src;

upon failure it returns NULL.

5.145.4.3 void DDS OctetBuﬀer free (unsigned char ∗ buﬀer)

Delete an OctetBuﬀer.

Precondition:

buffer must be either NULL, or must have been created using DDS -

OctetBuﬀer alloc() (p. 453), DDS OctetBuﬀer dup() (p. 453)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

454 Module Documentation

Parameters:

buﬀer <<in>> ( p. 200) The buﬀer to delete.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.146 Sequence Support 455

5.146 Sequence Support

The FooSeq (p. 1494) interface allows you to work with variable-length collec-

tions of homogeneous data.

Modules

Built-in Sequences

Deﬁnes sequences of primitive data type.

Classes

struct FooSeq

<<inter face>> (p. 199) <<generic>> (p. 199) A type-safe, ordered col-

lection of elements. The type of these elements is referred to in this docu-

mentation as Foo (p. 1443).

5.146.1 Detailed Description

The FooSeq (p. 1494) interface allows you to work with variable-length collec-

tions of homogeneous data.

This interface is instantiated for each concrete element type in order to provide

compile-time type safety to applications. The Built-in Sequences (p. 120) are

pre-deﬁned instantiations for the primitive data types.

When you use the rtiddsgen (p. 220) code generation tool, it will automatically

generate concrete sequence instantiations for each of your own custom types.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

456 Module Documentation

5.147 String Support

<<eXtension>> ( p. 199) String creation, cloning, assignment, and deletion.

Functions

char ∗ DDS String alloc (size t length)

Create a new empty string that can hold up to length characters.

char ∗ DDS String dup (const char ∗str)

Clone a string. Creates a new string that duplicates the value of string.

void DDS String free (char ∗str)

Delete a string.

DDS Wchar ∗ DDS Wstring alloc (DDS UnsignedLong length)

Create a new empty string that can hold up to length wide characters.

DDS UnsignedLong DDS Wstring length (const DDS Wchar

∗str)

Get the number of wide characters in the given string.

DDS Wchar ∗ DDS Wstring copy (DDS Wchar ∗dst, const DDS -

Wchar ∗src)

Copy the source string over the destination string reallocating the space if

it’s necessary.

DDS Wchar ∗ DDS Wstring copy and widen (DDS Wchar ∗dst,

const char ∗src)

Copy the source string over the destination string, widening each character.

DDS Wchar ∗ DDS Wstring dup (const DDS Wchar ∗str)

Clone a string of wide characters. Creates a new string that duplicates the

value of string.

DDS Wchar ∗ DDS Wstring dup and widen (const char ∗str)

Clone a string of characters as a string of wide characters.

void DDS Wstring free (DDS Wchar ∗str)

Delete a string.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.147 String Support 457

5.147.1 Detailed Description

<<eXtension>> ( p. 199) String creation, cloning, assignment, and deletion.

The methods in this class ensure consistent cross-platform implementations for

string creation (DDS String alloc() (p. 458)), deletion (DDS String free()

(p. 459)), and cloning (DDS String dup() (p. 459)) that preserve the mutable

value type semantics. These are to be viewed as methods that deﬁne a string

class whose data is represented by a ’char∗’.

5.147.2 Conventions

The following conventions govern the memory management of strings in RTI

Connext.

The DDS implementation ensures that when value types containing

strings are passed back and forth to the DDS APIs, the strings are cre-

ated/deleted/assigned/cloned using the string class methods.

– Value types containing strings have ownership of the contained string.

Thus, when a value type is deleted, the contained string ﬁeld is also

deleted.

– DDS StringSeq (p. 929) is a value type that contains strings;

it owns the memory for the contained strings. When a DDS -

StringSeq (p. 929) is ass igned or deleted, the contained strings are

also assigned or deleted respectively.

The user must ensure that when value types containing strings

are passed back and forth to the DDS APIs, the strings are cre-

ated/deleted/assigned/cloned using the String class methods.

The representation of a string in C/C++ unfortunately does not allow programs

to detect how much memory has been allocated for a string. RTI Connext must

therefore make some assumptions when a user requests that a string be copied

into. The following rules apply when RTI Connext is copying into a string or

string sequence:

If the ’char∗’ is NULL, RTI Connext will log a warning and allocate a new

string on behalf of the user. To avoid leaking memory, you must ensure

that the string will be freed (see Usage ( p. 458) below).

If the ’char∗’ is not NULL, RTI Connext will assume that you are man-

aging the string’s m em ory yourself and have allocated enough memory to

store the s tring to be copied. RTI Connext will copy into your memory;

to avoid memory corruption, be sure to allocate enough of it. Also, do not

pass structures containing junk pointers into RTI Connext; you are likely

to crash.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

458 Module Documentation

5.147.3 Usage

This requirement can generally be assured by adhering to the following idiom

for manipulating strings.

Always use

DDS_String_alloc() to create,

DDS_String_dup() to clone,

DDS_String_free() to delete

a string ’char*’ that is passed back and forth between

user code and the DDS C/C++ APIs.

Not adhering to this idiom can result in bad pointers, and incorrect memory

being freed.

In addition, the user code should be vigilant to avoid memory leaks. It is good

practice to:

Balance occurrences of DDS String alloc() (p. 458), DDS String -

dup() (p. 459), with matching occurrences of DDS String free()

(p. 459) in the code.

Finalize value types containing strings. In C++ the destructor accom-

plishes this automatically. in C, explicit ”destructor” functions are pro-

vided; these functions are typically called ”ﬁnalize.”

See also:

DDS StringSeq (p. 929)

5.147.4 Function Documentation

5.147.4.1 char∗ DDS String alloc (size t length)

Create a new empty string that can hold up to length characters.

A string created by this method must be deleted using DDS String free()

(p. 459).

This function will allocate enough memory to hold a string of length characters,

plus one additional byte to hold the NULL terminating character.

Parameters:

length <<in>> ( p. 200) Capacity of the string.

Returns:

A newly created non-NULL string upon success or NULL upon failure.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.147 String Support 459

Examples:

HelloWorld.cxx.

5.147.4.2 char∗ DDS String dup (const char ∗ str)

Clone a string. Creates a new string that duplicates the value of string.

A string created by this method must be deleted using DDS String free()

(p. 459)

Parameters:

str <<in>> ( p. 200) The string to duplicate.

Returns:

If string == NULL, this method always returns NULL. Otherwise, upon

success it returns a newly created string whose value is string; upon failure

it returns NULL.

5.147.4.3 void DDS String free (char ∗ str)

Delete a string.

Precondition:

string must be either NULL, or must have been created using DDS -

String alloc() (p. 458), DDS String dup() (p. 459)

Parameters:

str <<in>> ( p. 200) The string to delete.

Examples:

HelloWorld.cxx.

5.147.4.4 DDS Wchar∗ DDS Wstring alloc (DDS UnsignedLong

length)

Create a new empty string that can hold up to length wide characters.

A string created by this method must be deleted using DDS Wstring free()

(p. 462)

This function will allocate enough memory to hold a string of length characters,

plus one additional wide character to hold the NULL terminator.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

460 Module Documentation

Parameters:

length <<in>> ( p. 200) Capacity of the string.

Returns:

A newly created non-NULL string upon success or NULL upon failure.

5.147.4.5 DDS UnsignedLong DDS Wstring length (const

DDS Wchar ∗ str)

Get the number of wide characters in the given string.

The result does not count the terminating zero character.

Parameters:

str <<in>> ( p. 200) A non-NULL string.

Returns:

The number of wide characters in the string.

5.147.4.6 DDS Wchar∗ DDS Wstring copy (DDS Wchar ∗ dst,

const DDS Wchar ∗ src)

Copy the source string over the destination string reallocating the space if it’s

necessary.

Parameters:

dst

src

Returns:

dst

5.147.4.7 DDS Wchar∗ DDS Wstring copy and widen

(DDS Wchar ∗ dst, const char ∗ src)

Copy the source string over the destination string, widening each character.

Parameters:

dst <<in>> ( p. 200) A non-NULL string to be overwritten by src.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

5.147 String Support 461

src <<in>> ( p. 200) A non-NULL string to be copied over dst

Returns:

dst

5.147.4.8 DDS Wchar∗ DDS Wstring dup (const DDS Wchar ∗

str)

Clone a string of wide characters. Creates a new string that duplicates the value

of string.

A string created by this method must be deleted using DDS Wstring free()

(p. 462).

Parameters:

str <<in>> ( p. 200) The string to duplicate.

Returns:

If string == NULL, this method always returns NULL. Otherwise, upon

success it returns a newly created string whose value is string; upon failure

it returns NULL.

5.147.4.9 DDS Wchar∗ DDS Wstring dup and widen (const char ∗

str)

Clone a string of characters as a string of wide characters.

A string created by this method must be deleted using DDS Wstring free()

(p. 462)

Parameters:

str <<in>> ( p. 200) The string to duplicate.

Returns:

If string == NULL, this method always returns NULL. Otherwise, upon

success it returns a newly created string whose value is string; upon failure

it returns NULL.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

462 Module Documentation

5.147.4.10 void DDS Wstring free (DDS Wchar ∗ str)

Delete a string.

Precondition:

string must either NULL, or must have been created using DDS -

Wstring alloc() (p. 459), DDS Wstring dup() (p. 461), or DDS -

Wstring replace()

Parameters:

str <<in>> ( p. 200) The string to delete.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

Chapter 6

Class Documentation

6.1 DDS AckResponseData t Struct Reference

Data payload of an application-level acknowledgment.

Public Attributes

struct DDS OctetSeq value

a sequence of octets

6.1.1 Detailed Description

Data payload of an application-level acknowledgment.

6.1.2 Member Data Documentation

6.1.2.1 struct DDS OctetSeq DDS AckResponseData t::value

[read]

a sequence of octets

[default] empty (zero-length)

[range] Octet sequence of length [0, DDS -

DataReaderResourceLimitsQosPolicy::max app ack response length

(p. 533)],

464 Class Documentation

6.2 DDS AllocationSettings t Struct Reference

Resource allocation settings.

Public Attributes

DDS Long initial count

The initial count of resources.

DDS Long max count

The maximum count of resources.

DDS Long incremental count

The incremental count of resources.

6.2.1 Detailed Description

Resource allocation settings.

QoS:

DDS DomainParticipantResourceLimitsQosPolicy (p. 593)

6.2.2 Member Data Documentation

6.2.2.1 DDS Long DDS AllocationSettings t::initial count

The initial count of resources.

The initial resources to be allocated.

[default] It depends on the case.

[range] [0, 1 million], < max count, (or = max count only if increment count

== 0)

6.2.2.2 DDS Long DDS AllocationSettings t::max count

The maximum count of resources.

The maximum resources to be allocated.

[default] Depends on the case.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.2 DDS AllocationSettings t Struct Reference 465

[range] [1, 1 million] or DDS LENGTH UNLIMITED (p. 371), > initial -

count (or = initial count only if increment count == 0)

6.2.2.3 DDS Long DDS AllocationSettings t::incremental count

The incremental count of resources.

The resource to be allocated when more resources are needed.

[default] Depends on the case.

[range] -1 (Double the amount of extra memory allocated each time memory

is needed) or [1,1 million] (or = 0 only if initial count == max count)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

466 Class Documentation

6.3 DDS AsynchronousPublisherQosPolicy

Struct Reference

Conﬁgures the mechanism that sends user data in an external middleware

thread.

Public Attributes

DDS Boolean disable asynchronous write

Disable asynchronous publishing.

struct DDS ThreadSettings t thread

Settings of the publishing thread.

DDS Boolean disable asynchronous batch

Disable asynchronous batch ﬂushing.

struct DDS ThreadSettings t asynchronous batch thread

Settings of the batch ﬂushing thread.

6.3.1 Detailed Description

Conﬁgures the mechanism that sends user data in an external middleware

thread.

Speciﬁes the asynchronous publishing and asynchronous batch ﬂushing settings

of the DDSPublisher (p. 1346) instances.

The QoS policy speciﬁes whether asynchronous publishing and asynchronous

batch ﬂushing are e nabled for the DDSDataWriter (p. 1113) entities belong-

ing to this DDSPublisher (p. 1346). If so, the publisher will spawn up to

two threads, one for asynchronous publishing and one for asynchronous batch

ﬂushing.

See also:

DDS BatchQosPolicy (p. 476).

DDS PublishModeQosPolicy (p. 853).

Entity:

DDSPublisher (p. 1346)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.3 DDS AsynchronousPublisherQosPolicy Struct Reference 467

Properties:

RxO (p. 340) = N/A

Changeable (p. 340) = NO (p. 340)

6.3.2 Usage

You can use this QoS policy to reduce the amount of time your application

thread s pends sending data.

You can also use it, along with DDS PublishModeQosPolicy (p. 853) and

a DDSFlowController (p. 1259), to send large data reliably. ”Large” in this

context means that the data that cannot be sent as a single packet by a net-

work transport. For example, to s end data larger than 63K reliably using

UDP/IP, you must conﬁgure RTI Connext to fragment the data and send it

asynchronously.

The asynchronous publisher thread is shared by all DDS -

ASYNCHRONOUS PUBLISH MODE QOS (p. 422) DDSDataWriter

(p. 1113) instances that belong to this publisher and handles their data

transmission chores.

The asynchronous batch ﬂushing thread is shared by all DDSDataWriter

(p. 1113) instances with batching enabled that belong to this publisher.

This QoS policy also allows you to adjust the se ttings of the asynchronous

publishing and the asynchronous batch ﬂushing threads. To use diﬀerent threads

for two diﬀerent DDSDataWriter (p. 1113) entities, the instances must belong

to diﬀerent DDSPublisher (p. 1346) instances.

A DDSPublisher (p. 1346) must have asynchronous publishing enabled for its

DDSDataWriter (p. 1113) instances to write asynchronously.

A DDSPublisher (p. 1346) must have asynchronous batch ﬂushing enabled in

order to ﬂush the batches of its DDSDataWriter (p. 1113) instances asyn-

chronously. However, no as ynchronous batch ﬂushing thread will be started

until the ﬁrst DDSDataWriter (p. 1113) instance with batching enabled is

created from this DDSPublisher (p. 1346).

6.3.3 Member Data Documentation

6.3.3.1 DDS Boolean DDS -

AsynchronousPublisherQosPolicy::disable -

asynchronous write

Disable asynchronous publishing.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

468 Class Documentation

If set to DDS BOOLEAN TRUE (p. 298), any DDSDataWriter (p. 1113)

created with DDS ASYNCHRONOUS PUBLISH MODE QOS (p. 422)

will fail with DDS RETCODE INCONSISTENT POLICY (p. 315).

[default] DDS BOOLEAN FALSE (p. 299)

6.3.3.2 struct DDS ThreadSettings t DDS -

AsynchronousPublisherQosPolicy::thread

[read]

Settings of the publishing thread.

There is only one asynchronous publishing thread per DDSPublisher (p. 1346).

[default] priority below normal.

The actual value depends on your architecture:

For Windows: -2

For Solaris: OS default priority

For Linux: OS default priority

For LynxOS: 13

For Integrity: 80

For VxWorks: 110

For all others: OS default priority.

[default] The actual value depends on your architecture:

For Windows: OS default stack size

For Solaris: OS default stack size

For Linux: OS default stack size

For LynxOS: 4∗16∗1024

For Integrity: 4∗20∗1024

For VxWorks: 4∗16∗1024

For all others: OS default stack size.

[default] mask = DDS THREAD SETTINGS KIND MASK -

DEFAULT (p. 329)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.3 DDS AsynchronousPublisherQosPolicy Struct Reference 469

6.3.3.3 DDS Boolean DDS -

AsynchronousPublisherQosPolicy::disable -

asynchronous batch

Disable asynchronous batch ﬂushing.

If set to DDS BOOLEAN TRUE (p. 298), any DDSDataWriter

(p. 1113) created with batching enabled will fail with DDS RETCODE -

INCONSISTENT POLICY (p. 315).

If DDS BatchQosPolicy::max ﬂush delay (p. 478) is dif-

ferent than DDS DURATION INFINITE (p. 305), DDS -

AsynchronousPublisherQosPolicy::disable asynchronous batch

(p. 469) must be set DDS BOOLEAN FALSE (p. 299).

[default] DDS BOOLEAN FALSE (p. 299)

6.3.3.4 struct DDS ThreadSettings t DDS -

AsynchronousPublisherQosPolicy::asynchronous batch -

thread [read]

Settings of the batch ﬂushing thread.

There is only one asynchronous batch ﬂushing thread per DDSPublisher

(p. 1346).

[default] priority below normal.

The actual value depends on your architecture:

For Windows: -2

For Solaris: OS default priority

For Linux: OS default priority

For LynxOS: 13

For Integrity: 80

For VxWorks: 110

For all others: OS default priority.

[default] The actual value depends on your architecture:

For Windows: OS default stack size

For Solaris: OS default stack size

For Linux: OS default stack size

For LynxOS: 4∗16∗1024

For Integrity: 4∗20∗1024

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

470 Class Documentation

For VxWorks: 4∗16∗1024

For all others: OS default stack size.

[default] mask = DDS THREAD SETTINGS KIND MASK -

DEFAULT (p. 329)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.4 DDS AvailabilityQosPolicy Struct Reference 471

6.4 DDS AvailabilityQosPolicy Struct Refer -

ence

Conﬁgures the availability of data.

Public Attributes

DDS Boolean enable required subscriptions

Enables support for required subscriptions in a DDSDataWriter ( p. 1113).

struct DDS Duration t max data availability waiting time

Deﬁnes how much time to wait before delivering a sample to the application

without having received some of the prev ious samples.

struct DDS Duration t max endpoint availability waiting time

Deﬁnes how much time to wait to discover DataWriters providing samples

for the same data source (virtual GUID).

struct DDS EndpointGroupSeq required matched endpoint -

groups

A sequence of endpoint groups.

6.4.1 Detailed Description

Conﬁgures the availability of data.

Entity:

DDSDataReader (p. 1087), DDSDataWriter (p. 1113)

Properties:

RxO (p. 340) = NO

Changeable (p. 340) = YES (p. 340) (only on a DDSDataWriter

(p. 1113) except for the member DDS AvailabilityQosPolicy::enable -

required subscriptions (p. 473))

6.4.2 Usage

This QoS policy is used in the context of two features:

Collaborative DataWriters

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

472 Class Documentation

Required Subscriptions

Collaborative DataWriters

The Collaborative DataWriters feature allows having multiple DataWriters pub-

lishing samples from a common logical data source. The DataReaders will

combine the samples coming from the DataWriters in order to reconstruct the

correct order at the source.

This QoS policy allows you to conﬁgure the ordering and combination process

in the DataReader and can be used to support two diﬀerent use cases:

Ordered delivery of samples with RTI Persistence Service: When

a late-joining DataReader conﬁgured with DDS DurabilityQosPolicy

(p. 614) set to DDS PERSISTENT DURABILITY QOS (p. 349) or

DDS TRANSIENT DURABILITY QOS (p. 349) joins a DDS do-

main, it will start receiving historical samples from multiple DataWrit-

ers. For example, if the original DataWriter is still alive, the newly cre-

ated DataReader will receive samples from the original DataWriter and

one or more RTI Persistence Service DataWriters (PRSTDataWriters).

This policy can be used to conﬁgure the sample ordering process on the

DataReader.

Ordered delivery of samples with Group Ordered Acce ss: This

policy can also be used to conﬁgure the sample ordering process when

the Subscriber is conﬁgured with DDS PresentationQosPolicy (p. 823)

access scope set to DDS GROUP PRESENTATION QOS (p. 352).

In this case, the Subscriber must deliver in order the samples published

by a group of DataWriters that belong to the same Publisher and have

access scope set to DDS GROUP PRESENTATION QOS (p. 352).

Each sample published in a DDS domain for a given logical data source is

uniquely identiﬁed by a pair (virtual GUID, virtual sequence number). Samples

from the same data source (same virtual GUID) can be published by diﬀerent

DataWriters. A DataReader will deliver a sample (VGUIDn, VSNm) to the

application if one of the following conditions is satisﬁed:

(VGUIDn, VSNm-1) has already been delivered to the application.

All the known DataWriters publishing VGUIDn have announced that they

do not have (VGUIDn, VSNm-1).

None of the known DataWriters publishing GUIDn have announced po-

tential availability of (VGUIDn, VSNm-1) and both timeouts in this QoS

policy have expired.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.4 DDS AvailabilityQosPolicy Struct Reference 473

A DataWriter announces potential availability of samples by using virtual heart-

beats (HBs).

When DDS PresentationQosPolicy::access scope (p. 826) is set to

DDS TOPIC PRESENTATION QOS (p. 352) or DDS INSTANCE -

PRESENTATION QOS (p. 352), the virtual HB contains information about

the samples contained in the DDSDataWriter (p. 1113) history.

When DDS PresentationQosPolicy::access scop e (p. 826) is set to DDS -

GROUP PRESENTATION QOS (p. 352), the virtual HB contains infor-

mation about all DataWriters in the DDSPublisher (p. 1346).

The frequency at w hich virtual HBs are sent is controlled by the proto-

col parameters DDS RtpsReliableWriterProtocol t::virtual heartbeat -

period (p. 894) and DDS RtpsReliableWriterProtocol t::samples per -

virtual heartbeat (p. 895).

Required Subscriptions

In the context of Required Subscriptions, this QoS policy can be used to con-

ﬁgure a set of Required Subscriptions on a DDSDataWriter (p. 1113).

Required subscriptions are preconﬁgured, named subscriptions that may leave

and subsequently rejoin the network from time to time, at the same or diﬀerent

phys ical locations. Any time a required subscription is disconnected, any sam-

ples that would have been delivered to it are stored for delivery if and when the

subscription rejoins the network.

6.4.3 Member Data Documentation

6.4.3.1 DDS Boolean DDS AvailabilityQosPolicy::enable required -

subscriptions

Enables support for required subscriptions in a DDSDataWriter (p. 1113).

[default] DDS BOOLEAN FALSE (p. 299)

6.4.3.2 struct DDS Duration t DDS AvailabilityQosPolicy::max -

data availability waiting time [read]

Deﬁnes how much time to wait before delivering a sample to the application

without having received some of the previous samples.

Collaborative DataWriters

A sample identiﬁed by (VGUIDn, VSNm) will be delivered to the application if

this timeout expires for the sample and the following two conditions are satisﬁed:

None of the known DataWriters publishing VGUIDn have announced po-

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

474 Class Documentation

tential availability of (VGUIDn, VSNm-1).

The DataWriters for all the endpoint groups speciﬁed in required -

matched endpoint groups (p. 474) have been discovered or max -

endpoint availability waiting time (p. 474) has expired.

Required Subscriptions

This ﬁeld is not applicable to Required Subscriptions.

[default] DDS DURATION AUTO (p. 305) (DDS DURATION -

INFINITE (p. 305) for DDS GROUP PRESENTATION QOS (p. 352).

Otherwise, 0 seconds)

[range] [0, DDS DURATION INFINITE (p. 305)], DDS DURATION -

AUTO (p. 305)

6.4.3.3 struct DDS Duration t DDS AvailabilityQosPolicy::max -

endpoint availability waiting time [read]

Deﬁnes how much time to wait to discover DataWriters providing samples for

the same data source (virtual GUID).

Collaborative DataWriters

The set of endpoint groups that are required to provide samples for a data source

can be conﬁgured using required matched endpoint groups (p. 474).

A non-consecutive sample identiﬁed by (VGUIDn, VSNm) cannot be delivered

to the application unless DataWriters for all the e ndpoint groups in required -

matched endpoint groups (p. 474) are discovered or this timeout expires.

Required Subscriptions

This ﬁeld is not applicable to Required Subscriptions.

[default] DDS DURATION AUTO (p. 305) (DDS DURATION -

INFINITE (p. 305) for DDS GROUP PRESENTATION QOS (p. 352).

Otherwise, 0 seconds)

[range] [0, DDS DURATION INFINITE (p. 305)], DDS DURATION -

AUTO (p. 305)

6.4.3.4 struct DDS EndpointGroupSeq DDS -

AvailabilityQosPolicy::required matched endpoint groups

[read]

A sequence of endpoint groups.

Collaborative DataWriters

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.4 DDS AvailabilityQosPolicy Struct Reference 475

In the context of Collaborative DataWriters, it speciﬁes the set of endp oint

groups that are expected to provide samples for the same data source.

The quorum count in a group represents the number of DataWriters that must

be discovered for that group before the DataReader is allowed to provide non

consecutive samples to the application.

A DataWriter become s a member of an endpoint group by conﬁguring the role -

name in DDS DataWriterQos::publication name (p. 559).

Required Subscriptions

In the context of Required Subscriptions, it speciﬁes the set of Required Sub-

scriptions on a DDSDataWriter (p. 1113).

Each Required Subscription is speciﬁed by a name and a quorum count.

The quorum count represents the number of DataReaders that have to acknowl-

edge the sample before it can be considered fully acknowledged for that Required

Subscription.

A DataReader is associated with a Required Subscription by conﬁguring the

role name in DDS DataReaderQos::subscription name (p. 520).

[default] Empty sequence

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

476 Class Documentation

6.5 DDS BatchQosPolicy Struct Reference

Used to conﬁgure batching of multiple samples into a single network packet in

order to increase throughput for small samples.

Public Attributes

DDS Boolean enable

Speciﬁes whether or not batching is enabled.

DDS Long max data bytes

The maximum cumulative length of all serialized samples in a batch.

DDS Long max samples

The maximum number of samples in a batch.

struct DDS Duration t max ﬂush delay

The maximum ﬂush delay.

struct DDS Duration t source timestamp resolution

Batch source timestamp resolution.

DDS Boolean thread safe write

Determines whether or not the write operation is thread safe.

6.5.1 Detailed Description

Used to conﬁgure batching of multiple samples into a single network packet in

order to increase throughput for small samples.

This QoS policy conﬁgures the ability of the middleware to collect multiple user

data samples to be sent in a single network packet, to take advantage of the

eﬃciency of sending larger packets and thus increase eﬀective throughput.

This QoS policy can be used to dramatically increase eﬀective throughput for

small data samples. Usually, throughput for small samples (size < 2048 bytes) is

limited by CPU capacity and not by network bandwidth. Batching many smaller

samples to be sent in a single large packet will increase network utilization, and

thus throughput, in terms of samples per second.

Entity:

DDSDataWriter (p. 1113)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.5 DDS BatchQosPolicy Struct Reference 477

Properties:

RxO (p. 340) = NO

Changeable (p. 340) = UNTIL ENABLE (p. 340)

6.5.2 Member Data Documentation

6.5.2.1 DDS Boolean DDS BatchQosPolicy::enable

Speciﬁes whether or not batching is enabled.

[default] DDS BOOLEAN FALSE (p. 299)

6.5.2.2 DDS Long DDS BatchQosPolicy::max data bytes

The maximum cumulative length of all serialized samples in a batch.

A batch is ﬂushed automatically when this maximum is reached.

max data bytes does not include the meta data associated with the batch sam-

ples. Each sample has at least 8 bytes of meta data containing information such

as the timestamp and sequence number. The meta data can be as large as 52

bytes for keyed topics and 20 bytes for unkeyed topics.

Note: Batches must contain whole samples. If a new batch is started and its

initial sample causes the serialized size to exceed max

data bytes, RTI Connext

will send the sample in a single batch.

[default] 1024

[range] [1,DDS LENGTH UNLIMITED (p. 371)]

6.5.3 Consistency

The setting of DDS BatchQosPolicy::max data bytes (p. 477) must be

consistent with DDS BatchQosPolicy::max samples (p. 477). For these two

values to b e consistent, they cannot be both DDS LENGTH UNLIMITED

(p. 371).

6.5.3.1 DDS Long DDS BatchQosPolicy::max samples

The maximum number of samples in a batch.

A batch is ﬂushed automatically when this maximum is reached.

[default] DDS LENGTH UNLIMITED (p. 371)

[range] [1,DDS LENGTH UNLIMITED (p. 371)]

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

478 Class Documentation

6.5.4 Consistency

The setting of DDS BatchQosPolicy::max samples (p. 477) must be con-

sistent with DDS BatchQosPolicy::max data bytes (p. 477). For these two

values to b e consistent, they cannot be both DDS LENGTH UNLIMITED

(p. 371).

6.5.4.1 struct DDS Duration t DDS BatchQosPolicy::max ﬂush -

delay [read]

The maximum ﬂush delay.

A batch is ﬂushed automatically after the delay speciﬁed by this parameter.

The delay is measured from the time the ﬁrst sample in the batch is written by

the application.

[default] DDS DURATION INFINITE (p. 305)

[range] [0,DDS DURATION INFINITE (p. 305)]

6.5.5 Consistency

The setting of DDS BatchQosPolicy::max ﬂush delay (p. 478) must

be consistent with DDS AsynchronousPublisherQosPolicy::disable -

asynchronous batch (p. 469) and DDS BatchQosPolicy::thread safe -

write (p. 479). If the delay is diﬀerent than DDS DURATION -

INFINITE (p. 305), DDS AsynchronousPublisherQosPolicy:: disable -

asynchronous batch (p. 469) must be set to DDS BOOLEAN FALSE

(p. 299) and DDS BatchQosPolicy::thread safe write (p. 479) must be set

to DDS BOOLEAN TRUE (p. 298).

6.5.5.1 struct DDS Duration t DDS BatchQosPolicy::source -

timestamp resolution [read]

Batch source timestamp resolution.

The value of this ﬁeld determines how the source timestamp is associated with

the samples in a batch.

A sample written with timestamp ’t’ inherits the source timestamp ’t2’ associ-

ated with the previous sample unless (’t’ - ’t2’) > source timestamp res olution.

If source timestamp resolution is set to DDS DURATION INFINITE

(p. 305), every sample in the batch will share the source timestamp associated

with the ﬁrst sample.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.5 DDS BatchQosPolicy Struct Reference 479

If source times tamp resolution is set to zero, every sample in the batch will

contain its own source timestamp corresponding to the moment when the sample

was written.

The performance of the batching process is better when source timestamp -

resolution is set to DDS DURATION INFINITE (p. 305).

[default] DDS DURATION INFINITE (p. 305)

[range] [0,DDS DURATION INFINITE (p. 305)]

6.5.6 Consistency

The setting of DDS BatchQosPolicy::source timestamp resolution

(p. 478) must be consistent with DDS BatchQosPolicy::thread safe write

(p. 479). If DDS BatchQosPolicy::thread safe write (p. 479) is set to

DDS BOOLEAN FALSE (p. 299), DDS BatchQosPolicy::source -

timestamp resolution (p. 478) must be set to DDS DURATION -

INFINITE (p. 305).

6.5.6.1 DDS Boolean DDS BatchQosPolicy::thread safe write

Determines whether or not the write operation is thread safe.

If this parameter is set to DDS BOOLEAN TRUE (p. 298), multiple threads

can call write on the DDSDataWriter (p. 1113) concurrently.

[default] DDS BOOLEAN TRUE (p. 298)

6.5.7 Consistency

The setting of DDS BatchQosPolicy::thread safe write (p. 479) must

be consistent with DDS BatchQosPolicy::source timestamp resolution

(p. 478). If DDS BatchQosPolicy::thread safe write (p. 479) is se t

to DDS BOOLEAN FALSE (p. 299), DDS BatchQosPolicy::source -

timestamp resolution (p. 478) must be set to DDS DURATION -

INFINITE (p. 305).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

480 Class Documentation

6.6 DDS BooleanSeq Struct Reference

Instantiates FooSeq (p. 1494) < DDS Boolean (p. 301) >.

6.6.1 Detailed Description

Instantiates FooSeq (p. 1494) < DDS Boolean (p. 301) >.

Instantiates:

<<generic>> ( p. 199) FooSeq (p. 1494)

See also:

DDS Boolean (p. 301)

FooSeq (p. 1494)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.7 DDS BuiltinTopicKey t Struct Reference 481

6.7 DDS BuiltinTopicKey t Struct Reference

The key type of the built-in topic types.

Public Attributes

DDS BUILTIN TOPIC KEY TYPE NATIVE value [DDS BUILTIN -

TOPIC KEY TYPE NATIVE LENGTH]

An array of four integers that uniquely represents a remote DDSEntity

( p. 1253).

6.7.1 Detailed Description

The key type of the built-in topic types.

Each remote DDSEntity (p. 1253) to be discovered is can be uniquely identiﬁed

by this key. This is the key of all the built-in topic data types.

See also:

DDS ParticipantBuiltinTopicData (p. 816)

DDS TopicBuilti nTopicData (p. 958)

DDS PublicationBuiltinTopicData (p. 839)

DDS SubscriptionBuiltinTopicDat a (p. 936)

6.7.2 Member Data Documentation

6.7.2.1 DDS BUILTIN TOPIC KEY TYPE NATIVE

DDS BuiltinTopi cKey t::value[DDS BUILTIN TOPIC -

KEY TYPE NATIVE LENGTH]

An array of four integers that uniquely represents a remote DDSEntity

(p. 1253).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

482 Class Documentation

6.8 DDS BuiltinTopicReaderResourceLimits t

Struct Reference

Built-in topic reader’s resource limits.

Public Attributes

DDS Long initial samples

Initial number of samples.

DDS Long max samples

Maximum number of samples.

DDS Long initial infos

Initial number of sample infos.

DDS Long max infos

Maximum number of sample infos.

DDS Long initial outstanding reads

The initial number of outstanding reads that have not call ﬁnish yet on the

same built-in topic DDSDataReader ( p. 1087).

DDS Long max outstanding reads

The maximum number of outstanding reads that have not called ﬁnish yet on

the same built-in topic DDSDataReader ( p. 1087).

DDS Long max samples per read

Maximum number of samples that can be read/taken on a same b uilt-in topic

DDSDataReader ( p. 1087).

DDS Boolean disable fragmentation support

DDS Long max fragmented samples

DDS Long initial fragmented samples

DDS Long max fragmented samples per remote writer

DDS Long max fragments per sample

DDS Boolean dynamically allocate fragmented samples

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.8 DDS BuiltinTopicReaderResourceLimits t Struct Reference 483

6.8.1 Detailed Description

Built-in topic reader’s resource limits.

Deﬁnes the resources that can be used for a built-in-topic data reader.

A built-in topic data reader subscribes reliably to built-in topics containing

declarations of new entities or updates to existing e ntities in the domain. Keys

are used to diﬀerentiate among entities of the same type. RTI Connext assigns

a unique key to each entity in a domain.

Properties:

RxO (p. 340) = N/A

Changeable (p. 340) = NO (p. 340)

QoS:

DDS DiscoveryConﬁgQosPolicy (p. 573)

6.8.2 Member Data Documentation

6.8.2.1 DDS Long DDS BuiltinTopicReaderResourceLimits -

t::initial samples

Initial number of samples.

This should be a value between 1 and initial number of instance of the built-in-

topic reader, depending on how many instances are sending data concurrently.

[default] 64

[range] [1, 1 million], <= max samples

6.8.2.2 DDS Long DDS BuiltinTopicReaderResourceLimits -

t::max samples

Maximum number of samples.

This should be a value between 1 and max number of instance of the built-in-

topic reader, depending on how many instances are sending data concurrently.

Also, it should not be less than initial samples.

[default] DDS LENGTH UNLIMITED (p. 371)

[range] [1, 1 million] or DDS LENGTH UNLIMITED (p. 371), >= initial -

samples

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

484 Class Documentation

6.8.2.3 DDS Long DDS BuiltinTopicReaderResourceLimits -

t::initial infos

Initial number of sample infos.

The initial number of info units that a built-in topic DDSDataReader

(p. 1087) can have. Info units are used to store DDS SampleInfo (p. 912).

[default] 64

[range] [1, 1 million] <= max infos

6.8.2.4 DDS Long DDS BuiltinTopicReaderResourceLimits -

t::max infos

Maximum number of sample infos.

The maximum number of info units that a built-in topic DDSDataReader

(p. 1087) can use to store DDS SampleInfo (p. 912).

[default] DDS LENGTH UNLIMITED (p. 371)

[range] [1, 1 million] or DDS LENGTH UNLIMITED (p. 371), >= initial -

infos

6.8.2.5 DDS Long DDS BuiltinTopicReaderResourceLimits -

t::initial outstanding reads

The initial number of outstanding reads that have not call ﬁnish yet on the

same built-in topic DDSDataReader (p. 1087).

[default] 2

[range] [1, 65536] or DDS LENGTH UNLIMITED (p. 371) <= max -

outstanding reads

6.8.2.6 DDS Long DDS BuiltinTopicReaderResourceLimits -

t::max outstanding reads

The maximum number of outstanding reads that have not called ﬁnish yet on

the same built-in topic DDSDataReader (p. 1087).

[default] DDS LENGTH UNLIMITED (p. 371)

[range] [1, 65536] or DDS LENGTH UNLIMITED (p. 371), >= initial -

outstanding reads

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.8 DDS BuiltinTopicReaderResourceLimits t Struct Reference 485

6.8.2.7 DDS Long DDS BuiltinTopicReaderResourceLimits -

t::max samples per read

Maximum number of samples that can be read/taken on a same built-in topic

DDSDataReader (p.

1087).

[default] 1024

[range] [1, 65536]

6.8.2.8 DDS Boolean DDS BuiltinTopicReaderResourceLimits -

t::disable fragmentat ion support

6.8.2.9 DDS Long DDS BuiltinTopicReaderResourceLimits -

t::max fragmente d samples

6.8.2.10 DDS Long DDS BuiltinTopicReaderResourceLimits -

t::initial fragmented samples

6.8.2.11 DDS Long DDS BuiltinTopicReaderResourceLimits -

t::max fragmented samples per remote writer

6.8.2.12 DDS Long DDS BuiltinTopicReaderResourceLimits -

t::max fragments per sample

6.8.2.13 DDS Boolean DDS BuiltinTopicReaderResourceLimits -

t::dynamically allocate fragmented samples

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

486 Class Documentation

6.9 DDS ChannelSettings t Struct Reference

Type used to conﬁgure the properties of a channel.

Public Attributes

struct DDS TransportMulticastSetti ngsSeq multicast settings

A sequence of DDS TransportMulticastSettings t ( p. 980) used to con-

ﬁgure the multicast addresses assoc iated with a channel.

char ∗ ﬁlter expression

A logical expression used to determine the data that will be published in the

channel.

DDS Long priority

Publication priority.

6.9.1 Detailed Description

Type used to conﬁgure the properties of a channel.

QoS:

DDS MultiChannelQosPolicy (p. 796)

6.9.2 Member Data Documentation

6.9.2.1 struct DDS TransportMulticastSettingsSeq

DDS ChannelSettings t::multicast settings [read]

A sequence of DDS TransportMulticastSettings t (p. 980) used to conﬁg-

ure the multicast addresses associated with a channel.

The sequence cannot be empty.

The maximum number of multicast locators in a channel is limited to four (A

locator is deﬁned by a transport alias, a multicast address and a port)

[default] Empty sequence (invalid value)

6.9.2.2 char∗ DDS ChannelSettings t::ﬁlter expression

A logical expression used to determine the data that will be published in the

channel.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.9 DDS ChannelSettings t Struct Reference 487

If the expression evaluates to TRUE, a sample will be published on the channel.

An empty string always evaluates the expression to TRUE.

A NULL value is not allowed.

The syntax of the expression will depend on the value of DDS -

MultiChannelQosPolicy::ﬁlter name (p. 798)

Important: This value must be an allocated string with DDS String alloc

(p. 458) or DDS String dup (p. 459). It should not be assigned to a string

constant.

The ﬁlter expression length (including NULL-

terminated character) cannot be greater than DDS -

DomainParticipantResourceLimitsQosPolicy::channel ﬁlter -

expression max length (p. 610).

See also:

Queries and Filters Syntax (p. 208)

[default] NULL (invalid value)

6.9.2.3 DDS Long DDS ChannelSettings t::priority

Publication priority.

A positive integer value designating the relative priority of the channel, used to

determine the transmission order of pending writes.

Use of publication priorities requires the asynchronous publisher (DDS -

ASYNCHRONOUS PUBLISH MODE QOS (p. 422)) with DDS -

FlowControllerProperty t::scheduling policy (p. 750) set to DDS -

HPF FLOW CONTROLLER SCHED POLICY (p. 90).

Larger numbers have higher priority.

If the publication priority of the channel is any value other than DDS -

PUBLICATION PRIORITY UNDEFINED (p. 421), then the channel’s

priority will take precedence over the data writer’s priority.

If the publication priority of the channel is set to DDS PUBLICATION -

PRIORITY UNDEFINED (p. 421), then the channel’s priority will be set

to the value of the data writer’s priority.

If the publicaton priority of both the data writer and the channel are DDS -

PUBLICATION PRIORITY UNDEFINED (p. 421), the channel will be

assigned the lowest priority value.

If the publication priority of the channel is DDS PUBLICATION -

PRIORITY AUTOMATIC (p. 421), then the channel will be assigned the

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

488 Class Documentation

priority of the largest publication priority of all samples in the channel. The

publication priority of each sample can be set in the DDS WriteParams t

(p. 1067) of the FooDataWriter::write w params (p. 1487) function.

[default] DDS PUBLICATION PRIORITY UNDEFINED (p. 421)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.10 DDS ChannelSettingsSeq Struct Reference 489

6.10 DDS ChannelSettingsSeq Struct Refer-

ence

Declares IDL sequence< DDS ChannelSettings t (p. 486) >.

6.10.1 Detailed Description

Declares IDL sequence< DDS ChannelSettings t (p. 486) >.

A sequence of DDS ChannelSettings t (p. 486) used to conﬁgure the

channels’ properties. If the length of the sequence is zero, the DDS -

MultiChannelQosPolicy (p. 796) has no eﬀect.

Instantiates:

<<generic>> ( p. 199) FooSeq (p. 1494)

See also:

DDS ChannelSettings t (p. 486)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

490 Class Documentation

6.11 DDS CharSeq Struct Reference

Instantiates FooSeq (p. 1494) < DDS Char (p. 299) >.

6.11.1 Detailed Description

Instantiates FooSeq (p. 1494) < DDS Char (p. 299) >.

Instantiates:

<<generic>> ( p. 199) FooSeq (p. 1494)

See also:

DDS Char (p. 299)

FooSeq (p. 1494)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.12 DDS ContentFilterProperty t Struct Reference 491

6.12 DDS ContentFilterProperty t Struct Ref-

erence

<<eXtension>> ( p.

199) Type used to provide all the required information

to enable content ﬁltering.

Public Attributes

char ∗ content ﬁlter topic name

Name of the Content-ﬁltered Topic associated with the Reader.

char ∗ related topic name

Name of the Topic related to the Content-ﬁltered Topic.

char ∗ ﬁlter class name

Identiﬁes the ﬁlter class this ﬁlter belongs to. RTPS can support multiple

ﬁlter classes (SQL, regular expressions, custom ﬁlters, etc).

char ∗ ﬁlter expression

The actual ﬁlter expression. Must be a valid expression for the ﬁlter class

speciﬁed using ﬁlterClassName.

struct DDS StringSeq expression parameters

Deﬁnes the value for each parameter in the ﬁlter expression.

6.12.1 Detailed Description

<<eXtension>> ( p. 199) Type used to provide all the required information

to enable content ﬁltering.

6.12.2 Member Data Documentation

6.12.2.1 char∗ DDS ContentFilterProperty t::content ﬁlter topic -

name

Name of the Content-ﬁltered Topic associated with the Reader.

6.12.2.2 char∗ DDS ContentFilte rProperty t::related topic name

Name of the Topic related to the C ontent-ﬁltered Topic.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

492 Class Documentation

6.12.2.3 char∗ DDS ContentFilterProperty t::ﬁlter class name

Identiﬁes the ﬁlter class this ﬁlter belongs to. RTPS can support multiple ﬁlter

classes (SQL, regular expressions, custom ﬁlters, etc).

6.12.2.4 char∗ DDS ContentFilterProperty t::ﬁlter expression

The actual ﬁlter expression. Must be a valid expression for the ﬁlter class

speciﬁed using ﬁlterClassName.

6.12.2.5 struct DDS StringSeq DDS Cont entFilterProperty -

t::expression parameters [read]

Deﬁnes the value for each parameter in the ﬁlter expression.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.13 DDS Cookie t Struct Reference 493

6.13 DDS Cookie t Struct Reference

<<eXtension>> ( p. 199) Sequence of bytes identifying a written data sample,

used when writing with parameters.

Public Attributes

struct DDS OctetSeq value

a sequence of octets

6.13.1 Detailed Description

<<eXtension>> ( p. 199) Sequence of bytes identifying a written data sample,

used when writing with parameters.

6.13.2 Member Data Documentation

6.13.2.1 struct DDS OctetSeq DDS Cookie t::value [read]

a sequence of octets

[default] Empty (zero-sized)

[range] Octet sequence of length [0,DDS -

DataWriterResourceLimitsQosPolicy::cookie max length]

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

494 Class Documentation

6.14 DDS CookieSeq Struct Reference

6.14.1 Detailed Description

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.15 DDS DatabaseQosPolicy Struct Reference 495

6.15 DDS DatabaseQosPolicy Struct Reference

Various threads and resource limits settings used by RTI Connext to control its

internal database.

Public Attributes

struct DDS ThreadSettings t thread

Database thread settings.

struct DDS Duration t shutdown timeout

The maximum wait time during a shutdown.

struct DDS Duration t cleanup period

The database thread will wake up at this rate to clean up the database.

struct DDS Duration t shutdown cleanup period

The clean-up period used during database shut-down.

DDS Long initial records

The initial number of total records.

DDS Long max skiplist level

The maximum level of the skiplist.

DDS Long max weak references

The maximum number of weak references.

DDS Long initial weak references

The initial number of weak references.

6.15.1 Detailed Description

Various threads and resource limits settings used by RTI Connext to control its

internal database.

RTI uses an internal in-memory ”database” to store information about entities

created locally as well as remote entities found during the discovery process.

This database uses a background thread to garbage-collect records related to

deleted entities. When the DDSDomainParticipant (p. 1139) that maintains

this database is deleted, it shuts down this thread.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

496 Class Documentation

The Database QoS policy is used to conﬁgure how RTI Connext manages its

database, including how often it cleans up, the priority of the database thread,

and limits on resources that may be allocated by the database.

You may be interested in modifying the DDS -

DatabaseQosPolicy::shutdown timeout (p. 497) and DDS -

DatabaseQosPolicy::shutdown cleanup period (p. 497) parameters

to decreas e the time it takes to delete a DDSDomainParticipant (p. 1139)

when your application is shutting down.

The DDS DomainParticipantR esourceLimitsQosPolicy (p. 593) controls

the memory allocation for elements stored in the database.

This QoS policy is an extension to the DDS standard.

Entity:

DDSDomainParticipant (p. 1139)

Properties:

RxO (p. 340) = N/A

Changeable (p. 340) NO (p. 340)

6.15.2 Member Data Documentation

6.15.2.1 struct DDS ThreadSettings t DDS -

DatabaseQosPolicy::thread [read]

Database thread settings.

There is only one database thread: the clean-up thread.

[default] priority low.

The actual value depends on your architecture:

For Windows: -3

For Solaris: OS default priority

For Linux: OS default priority

For LynxOS: 10

For INTEGRITY: 60

For VxWorks: 120

For all others: OS default priority.

[default] The actual value depends on your architecture:

For Windows: OS default stack size

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.15 DDS DatabaseQosPolicy Struct Reference 497

For Solaris: OS default stack size

For Linux: OS default stack size

For LynxOS: 16∗1024

For INTEGRITY: 20∗1024

For VxWorks: 16∗1024

For all others: OS default stack size.

[default] mask DDS THREAD SETTINGS STDIO (p. 329)

6.15.2.2 struct DDS Duration t DDS -

DatabaseQosPolicy::shutdown timeout

[read]

The maximum wait time during a shutdown.

The domain participant will exit after the timeout, even if the database has not

been fully cleaned up.

[default] 15 seconds

[range] [0,DDS DURATION INFINITE (p. 305)]

6.15.2.3 struct DDS Duration t DDS DatabaseQosPolicy::cleanup -

period [read]

The database thread will wake up at this rate to clean up the database.

[default] 61 seconds

[range] [0,1 year]

6.15.2.4 struct DDS Duration t DDS -

DatabaseQosPolicy::shutdown cleanup period

[read]

The clean-up period used during database shut-down.

[default] 1 second

[range] [0,1 year]

6.15.2.5 DDS Long DDS DatabaseQosPolicy::initial records

The initial number of total records.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

498 Class Documentation

[default] 1024

[range] [1,10 million]

6.15.2.6 DDS Long DDS DatabaseQosPolicy::max skiplist level

The maximum level of the skiplist.

The skiplist is used to keep records in the database. Usually, the search time is

log2(N), where N is the total number of records in one skiplist. However, once N

exceeds 2

∧

n, where n is the m aximum skiplist level, the search time will become

more and more linear. Therefore, the maximum level should be set such that

∧

n is larger than the maximum(N among all skiplists). Usually, the maximum

N is the maximum number of remote and local writers or readers.

[default] 14

[range] [1,31]

6.15.2.7 DDS Long DDS DatabaseQosPolicy::max weak references

The maximum number of weak references.

A weak reference is an internal data structure that refers to a record within RTI

Connext’ internal database. This ﬁeld conﬁgures the maximum number of such

references that RTI Connext may create.

The actual number of weak references is permitted to grow from an initial value

(indicated by DDS DatabaseQosPolicy::initial weak references (p. 499))

to this maximum. To prevent RTI Connext from allocating any weak references

after the system has reached a steady state, set the initial and maximum values

equal to one another. To indicate that the number of weak references should

continue to grow as needed indeﬁnitely, set this ﬁeld to DDS LENGTH -

UNLIMITED (p. 371). Be aware that although a single weak reference oc-

cupies very little memory, allocating a very large number of them can have a

signiﬁcant impact on your overall memory usage.

Tuning this value precisely is diﬃcult without intimate knowledge of the struc-

ture of RTI Connext’ database; doing so is an advanced feature not required

by most applications. The default value has been chosen to be suﬃcient for

reasonably large systems. If you believe you may nee d to m odify this value,

please consult with RTI support personnel for assistance.

[default] DDS LENGTH UNLIMITED (p. 371)

[range] [1, 100 million] or DDS LENGTH UNLIMITED (p. 371), >= ini-

tial weak references

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.15 DDS DatabaseQosPolicy Struct Reference 499

See also:

DDS DatabaseQosPolicy::initial weak references (p. 499)

6.15.2.8 DDS Long DDS DatabaseQosPolicy::initial weak -

references

The initial number of weak references.

See DDS DatabaseQosPolicy::max weak references (p. 498) for more in-

formation about what a weak reference is.

If the QoS set contains an initial weak references value that is too small to

ever grow to DDS DatabaseQosPolicy::max weak references (p. 498) us-

ing RTI Connext’ internal algorithm, this value will be adjusted upwards as

necessary. Subsequent accesses of this value will reveal the actual initial value

used.

Changing the value of this ﬁeld is an advanced feature; it is recommended that

you consult with RTI support personnel before doing so.

[default] 2049, which is the minimum initial value imposed by REDA when the

maximum is unlimited. If a lower value is speciﬁed, it will simply b e increased

to 2049 automatically.

[range] [1, 100 million], <= max weak references

See also:

DDS DatabaseQosPolicy::max weak references (p. 498)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

500 Class Documentation

6.16 DDS DataReaderCacheStatus Struct Ref-

erence

<<eXtension>> ( p. 199) The status of the reader’s cache.

Public Attributes

DDS LongLong sample count peak

The highest number of samples in the reader’s queue over the l ifetime of the

reader.

DDS LongLong sample count

The number of samples in the reader’s queue.

6.16.1 Detailed Description

<<eXtension>> ( p. 199) The status of the reader’s cache.

Entity:

DDSDataReader (p. 1087)

6.16.2 Member Data Documentation

6.16.2.1 DDS LongLong DDS DataReaderCacheStatus::sample -

count peak

The highest number of samples in the reader’s queue over the lifetime of the

reader.

6.16.2.2 DDS LongLong DDS DataReaderCacheStatus::sample -

count

The number of samples in the reader’s queue.

includes samples that may not yet be available to be read or taken by the user,

due to samples being received out of order or PRESENTATION (p. 351)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.17 DDS DataReaderProtocolQosPolicy Struct Reference 501

6.17 DDS DataReaderProtocolQosPolicy

Struct Reference

Along with DDS WireProtocolQosPolicy (p. 1059) and DDS -

DataWriterProtocolQosPolicy (p. 535), this QoS policy conﬁgures the

DDS on-the-network protocol (RTPS).

Public Attributes

struct DDS GUID t virtual guid

The virtual GUID (Global Unique Identiﬁer).

DDS UnsignedLong rtps object id

The RTPS Object ID.

DDS Boolean expects inline qos

Speciﬁes whether this DataReader expects inline QoS with every sample.

DDS Boolean disable positive acks

Whether the reader sends positive acknowledgements to writers.

DDS Boolean propagate dispose of unregistered instances

Indicates whether or not an instance can move to the DDS NOT ALIVE -

DISPOSED INSTANCE STATE ( p. 117) state without being in the

DDS ALIVE INSTANCE STATE ( p. 117) state.

struct DDS RtpsReliableReaderProtocol t rtps reliable reader

The reliable protocol deﬁned in RTPS.

6.17.1 Detailed Description

Along with DDS WireProtocolQosPolicy (p. 1059) and DDS -

DataWriterProtocolQosPolicy (p. 535), this QoS policy conﬁgures the

DDS on-the-network protocol (RTPS).

DDS has a standard protocol for packet (user and meta data) exchange be-

tween applications using DDS for communications. This QoS policy and DDS -

DataReaderProtocolQosPolicy (p. 501) give you control over conﬁgurable

portions of the protocol, including the conﬁguration of the reliable data delivery

mechanism of the protocol on a per DataWriter or DataReader basis.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

502 Class Documentation

These conﬁguration parameters control timing, timeouts, and give you the abil-

ity to tradeoﬀ between spee d of data loss detection and repair versus network

and C PU bandwidth use d to maintain reliability.

It is important to tune the reliability protocol (on a per DDSDataWriter

(p.

1113) and DDSDataReader (p. 1087) basis) to meet the requirements of

the end-user application so that data can be sent between DataWriters and

DataReaders in an eﬃcient and optimal manner in the presence of data loss.

You can also use this QoS policy to control how RTI Connext responds to

”slow” reliable DataReaders or ones that disconnect or are otherwise lost.

See DDS ReliabilityQosPolicy (p. 865) for more information on the per-

DataReader/DataWriter reliability conﬁguration. DDS HistoryQosPolicy

(p. 758) and DDS ResourceLimitsQosPolicy (p. 879) also play an impor-

tant role in the DDS reliable protocol.

This QoS policy is an extension to the DDS standard.

Entity:

DDSDataReader (p. 1087)

Properties:

RxO (p. 340) = N/A

Changeable (p. 340) = NO (p. 340)

6.17.2 Member Data Documentation

6.17.2.1 struct DDS GUID t DDS -

DataReaderProtocolQosPolicy::virtual guid

[read]

The virtual GUID (Global Unique Identiﬁer).

The virtual GUID is used to uniquely identify diﬀerent incarnations of the same

DDSDataReader (p. 1087).

The association between a DDSDataReader (p. 1087) and its persisted state

is done using the virtual GUID.

[default] DDS GUID AUTO (p. 309)

6.17.2.2 DDS UnsignedLong DDS -

DataReaderProtocolQosPolicy::rtps object id

The RTPS Object ID.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.17 DDS DataReaderProtocolQosPolicy Struct Reference 503

This value is used to determine the RTPS object ID of a data reader according

to the DDS-RTPS Interoperability Wire Protoc ol.

Only the last 3 bytes are used; the most signiﬁcant byte is ignored.

If the default value is speciﬁed, RTI Connext will automatically assign the object

ID based on a counter value (per participant) starting at 0x00800000. That

value is incremented for each new data reader.

A rtps object id value in the interval [0x00800000,0x00ﬀﬀﬀ] may collide with the

automatic values assigned by RTI Connext. In those cases, the recomendation

is not to use automatic object ID assigment.

[default] DDS RTPS AUTO ID (p. ??)

[range] [0,0x00ﬀﬀﬀ]

6.17.2.3 DDS Boolean DDS -

DataReaderProtocolQosPolicy::expects inline qos

Speciﬁes whether this DataReader expects inline QoS with every sample.

In RTI Connext, a DDSDataReader (p. 1087) nominally relies on Discov-

ery to propagate QoS on a matched DDSDataWriter (p. 1113). Alterna-

tively, a DDSDataReader (p. 1087) may get information on a matched DDS-

DataWriter (p. 1113) through QoS sent inline with a sample.

Asserting DDS DataReaderProtocolQosPolicy::expects inline qos

(p. 503) indicates to a matching DDSDataWriter (p. 1113) that this DDS-

DataReader (p. 1087) e xpects to receive inline QoS with every sample. The

complete set of inline QoS that a DDSDataWriter (p. 1113) may send inline

is speciﬁed by the Real-Time Publish-Subscribe (RTPS) Wire Interoperability

Protocol.

Because RTI Connext DDSDataWriter (p. 1113) and DDSDataReader

(p. 1087) cache Discovery information, inline QoS are largely redundant and thus

unecessary. Only for other stateless implementations whose DDSDataReader

(p. 1087) does not cache Discovery information is inline QoS necessary.

Also note that inline QoS are additional wire-payload that consume additional

bandwidth and serialization and deserialization time.

[default] DDS

BOOLEAN FALSE (p. 299)

6.17.2.4 DDS

Boolean DDS -

DataReaderProtocolQosPolicy::disable positive acks

Whether the reader sends positive acknowledgements to writers.

If set to DDS BOOLEAN TRUE (p. 298), the reader does not send positive

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

504 Class Documentation

acknowledgments (ACKs) in response to Heartbeat messages. The reader will

send negative acknowledgements (NACKs) when a Heartbeat advertises samples

that it has not received.

Otherwise, if set to DDS BOOLEAN FALSE (p. 299) (the default),

the reader will send ACKs to writers that expect ACKs (DDS -

DataWriterProtocolQosPolicy::disable positive acks (p. 537) = DDS -

BOOLEAN FALSE (p. 299)) and it will not send ACKs to writers that dis-

able ACKs (DDS DataWriterProtocolQosPolicy::disable positive acks

(p. 537) = DDS BOOLEAN TRUE (p. 298))

[default] DDS BOOLEAN FALSE (p. 299)

6.17.2.5 DDS Boolean DDS -

DataReaderProtocolQosPolicy::propagate -

dispose of unregistered instances

Indicates whether or not an instance can move to the DDS NOT ALIVE -

DISPOSED INSTANCE STATE (p. 117) state without b e ing in the

DDS ALIVE INSTANCE STATE (p. 117) state.

This ﬁeld only applies to keyed readers.

When the ﬁeld is set to DDS BOOLEAN TRUE (p. 298), the DataReader

will receive dispose notiﬁcations even if the instance is not alive.

To guarantee the key availability through the usage of the API Foo-

DataReader::get key value (p. 1472), this option should be used in combi-

nation DDS DataWriterProtocolQosPolicy::serialize key with dispose

(p. 538) on the DataWriter that should be set to DDS BOOLEAN TRUE

(p. 298).

[default] DDS BOOLEAN FALSE (p. 299)

6.17.2.6 struct DDS RtpsReli ableReaderProtocol t

DDS DataReaderProtocolQosPolicy::rtps reliable reader

[read]

The reliable protocol deﬁned in RTPS.

[default] min heartbeat response delay 0 seconds; max heartbeat response -

delay 0.5 seconds

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.18 DDS DataReaderProtocolStatus Struct Reference 505

6.18 DDS DataReaderProtocolStatus Struct

Reference

<<eXtension>> ( p. 199) The status of a reader’s internal protocol related

metrics, like the number of samples received, ﬁltered, rejected; and status of

wire protocol traﬃc.

Public Attributes

DDS LongLong received sample count

The number of user samples from a remote DataWriter received for the ﬁrst

time by a local DataReader.

DDS LongLong received sample count change

The incremental change in the number of user samples from a remote

DataWriter received for the ﬁrst time by a local DataReader since the last

time the status was read.

DDS LongLong received sample bytes

The number of bytes of user samples from a remote DataWriter received for

the ﬁrst time by a local DataReader.

DDS LongLong received sample bytes change

The incremental change in the number of bytes of user samples from a remote

DataWriter received for the ﬁrst time by a local DataReader since the last

time the status was read.

DDS LongLong duplicate sample count

The number of samples from a remote DataWriter received, not for the ﬁrst

time, by a local DataReader.

DDS LongLong duplicate sample count change

The incremental change in t he number of samples from a remote DataWriter

received, not for the ﬁrst time, by a local DataReader since the last time the

status was read.

DDS LongLong duplicate sample bytes

The number of bytes of samples from a remote DataWriter received, not for

the ﬁrst time, by a local DataReader.

DDS LongLong duplicate sample bytes change

The incremental change in the number of bytes of samples from a remote

DataWriter received, not for the ﬁrst time, by a local DataReader since the

last time the status was read.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

506 Class Documentation

DDS LongLong ﬁltered sample count

The number of user samples ﬁltered by the local DataReader due to Content-

Filtered Topics or Time-Based Filter.

DDS LongLong ﬁltered sample count change

The incremental change in the number of user samples ﬁltered by the local

DataReader due to Content-Filtered Topics or Time-Based Filter since the

last time the status was read.

DDS LongLong ﬁltered sample bytes

The number of bytes of user samples ﬁltered by the local DataReader due to

Content-Filtered Topics or Time-Based Filter.

DDS LongLong ﬁltered sample bytes change

The incremental change in the number of bytes of user samples ﬁltered by

the local DataReader due to Content-Filtered Topics or Time-Based Filter

since the last time the status was read.

DDS LongLong received heartbeat count

The number of Heartbeats from a remote DataWriter received by a local

DataReader.

DDS LongLong received heartbeat count change

The incremental change in the number of Heartbeats from a remote

DataWriter received by a local DataReader since the last time the status

was read.

DDS LongLong received heartbeat bytes

The number of bytes of Heartbeats from a remote DataWriter received by a

local DataReader.

DDS LongLong received heartbeat bytes change

The incremental change in the number of bytes of Heartbeats from a remote

DataWriter received by a local DataReader since the last time the status was

read.

DDS LongLong sent ack count

The number of ACKs sent from a local DataReader to a matching remote

DataWriter.

DDS LongLong sent ack count change

The incremental change in the number of ACKs sent from a local DataReader

to a matching remote DataWriter since the last time the status was read.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.18 DDS DataReaderProtocolStatus Struct Reference 507

DDS LongLong sent ack bytes

The number of bytes of ACKs sent from a local DataReader to a matching

remote DataWriter.

DDS LongLong sent ack bytes change

The incremental change in the number of bytes of ACKs sent from a local

DataReader to a matching remote DataWriter since the last time the status

was read.

DDS LongLong sent nack count

The number of NACKs sent from a local DataReader to a matching remote

DataWriter.

DDS LongLong sent nack count change

The incremental change in the number of NACKs sent from a local

DataReader to a matching remote DataWriter since the last time the sta-

tus was read.

DDS LongLong sent nack bytes

The number of bytes of NACKs sent from a local DataReader to a matching

remote DataWriter.

DDS LongLong sent nack bytes change

The incremental change in the number of bytes of NACKs sent from a local

DataReader to a matching remote DataWriter since the last time the status

was read.

DDS LongLong received gap count

The number of GAPs received from remote DataWriter to this DataReader.

DDS LongLong received gap count change

The incremental change in the number of GAPs received from remote

DataWriter to this DataReader since the last time the status was read.

DDS LongLong received gap bytes

The number of bytes of GAPs received from remote DataWriter to this

DataReader.

DDS LongLong received gap bytes change

The incremental change in the number of bytes of GAPs received from remote

DataWriter to this DataReader since the last time the status was read.

DDS LongLong rejected sample count

The number of times a sample is rejected due to exceptions in the receive

path.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

508 Class Documentation

DDS LongLong rejected sample count change

The incremental change in the number of times a sample is rejected due to

exceptions in the rece ive path since the last time the status was read.

struct DDS SequenceNumber t ﬁrst available sample sequence -

number

Sequence number of the ﬁrst available sample in a matched Datawriters reli-

ability queue.

struct DDS SequenceNumber t last available sample sequence -

number

Sequence number of the last available sample in a matched Datawriter’s re-

liability queue.

struct DDS SequenceNumber t last committed sample -

sequence number

Sequence number of the newest sample received from the matched DataWriter

committed to the DataReader’s queue.

DDS Long uncommitted sample count

Number of received samples that are not yet available to be read or taken,

due to being received out of order.

6.18.1 Detailed Description

<<eXtension>> ( p. 199) The status of a reader’s internal protocol related

metrics, like the number of samples received, ﬁltered, rejected; and status of

wire protocol traﬃc.

Entity:

DDSDataReader (p. 1087)

6.18.2 Member Data Documentation

6.18.2.1 DDS LongLong DDS -

DataReaderProtocolStatus::received sample count

The number of user samples from a remote DataWriter received for the ﬁrst

time by a local DataReader.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.18 DDS DataReaderProtocolStatus Struct Reference 509

6.18.2.2 DDS LongLong DDS -

DataReaderProtocolStatus::received sample count change

The incremental change in the number of user samples from a remote DataWriter

received for the ﬁrst time by a local DataReader since the last time the status

was read.

6.18.2.3 DDS LongLong DDS -

DataReaderProtocolStatus::received sample bytes

The number of bytes of user samples from a remote DataWriter received for the

ﬁrst time by a local DataReader.

6.18.2.4 DDS LongLong DDS -

DataReaderProtocolStatus::received sample bytes change

The incremental change in the number of bytes of user samples from a remote

DataWriter received for the ﬁrst time by a local DataReader since the last time

the status was read.

6.18.2.5 DDS LongLong DDS -

DataReaderProtocolStatus::duplicate sample count

The number of samples from a remote DataWriter received, not for the ﬁrst

time, by a local DataReader.

Such samples can be redundant, out-of-order, etc. and are not stored in the

reader’s queue.

6.18.2.6 DDS LongLong DDS -

DataReaderProtocolStatus::duplicate -

sample count change

The incremental change in the number of samples from a remote DataWriter

received, not for the ﬁrst time, by a local DataReader since the last time the

status was read.

Such samples can be redundant, out-of-order, etc. and are not stored in the

reader’s queue.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

510 Class Documentation

6.18.2.7 DDS LongLong DDS -

DataReaderProtocolStatus::duplicate sample bytes

The number of bytes of samples from a remote DataWriter received, not for the

ﬁrst time, by a local DataReader.

Such samples can be redundant, out-of-order, etc. and are not stored in the

reader’s queue.

6.18.2.8 DDS LongLong DDS -

DataReaderProtocolStatus::duplicate sample bytes change

The incremental change in the number of bytes of samples from a remote

DataWriter received, not for the ﬁrst time, by a local DataReader since the

last time the status was read.

Such samples can be redundant, out-of-order, etc. and are not stored in the

reader’s queue.

6.18.2.9 DDS LongLong DDS DataReaderProtocolStatus::ﬁltered -

sample count

The number of user samples ﬁltered by the local DataReader due to Content-

Filtered Topics or Time-Based Filter.

6.18.2.10 DDS LongLong DDS -

DataReaderProtocolStatus::ﬁltered sample count change

The incremental change in the number of user samples ﬁltered by the local

DataReader due to Content-Filtered Topics or Time-Based Filter since the last

time the status was read.

6.18.2.11 DDS LongLong DDS -

DataReaderProtocolStatus::ﬁltered sample bytes

The number of bytes of user samples ﬁltered by the lo c al DataReader due to

Content-Filtered Topics or Time-Based Filter.

6.18.2.12 DDS LongLong DDS -

DataReaderProtocolStatus::ﬁltered sample bytes change

The incremental change in the number of bytes of user samples ﬁltered by the

local DataReader due to Content-Filtered Topics or Time-Based Filter since the

last time the status was read.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.18 DDS DataReaderProtocolStatus Struct Reference 511

6.18.2.13 DDS LongLong DDS -

DataReaderProtocolStatus::received heartbeat count

The number of Heartbeats from a remote DataWriter received by a local

DataReader.

6.18.2.14 DDS LongLong DDS -

DataReaderProtocolStatus::received -

heartbeat count change

The incremental change in the number of Heartb e ats from a remote DataWriter

received by a local DataReader since the last time the status was read.

6.18.2.15 DDS LongLong DDS -

DataReaderProtocolStatus::received heartbeat bytes

The number of bytes of Heartbeats from a remote DataWriter received by a

local DataReader.

6.18.2.16 DDS LongLong DDS -

DataReaderProtocolStatus::received -

heartbeat bytes change

The incremental change in the number of bytes of Heartbeats from a remote

DataWriter received by a local DataReader since the last time the status was

read.

6.18.2.17 DDS LongLong DDS DataReaderProtocolStatus::sent -

ack count

The number of ACKs sent from a local DataReader to a matching remote

DataWriter.

6.18.2.18 DDS

LongLong DDS DataReaderProtocolStatus::sent -

ack count change

The incremental change in the number of ACKs sent from a local DataReader

to a matching remote DataWriter since the last time the status was read.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

512 Class Documentation

6.18.2.19 DDS LongLong DDS DataReaderProtocolStatus::sent -

ack bytes

The number of bytes of ACKs sent from a local DataReader to a matching

remote DataWriter.

6.18.2.20 DDS LongLong DDS DataReaderProtocolStatus::sent -

ack bytes change

The incremental change in the number of bytes of ACKs sent from a local

DataReader to a matching remote DataWriter since the last time the status

was read.

6.18.2.21 DDS LongLong DDS DataReaderProtocolStatus::sent -

nack count

The number of NACKs sent from a local DataReader to a matching remote

DataWriter.

6.18.2.22 DDS LongLong DDS DataReaderProtocolStatus::sent -

nack count change

The incremental change in the number of NACKs sent from a local DataReader

to a matching remote DataWriter since the last time the status was read.

6.18.2.23 DDS LongLong DDS DataReaderProtocolStatus::sent -

nack bytes

The number of bytes of NACKs sent from a local DataReader to a matching

remote DataWriter.

6.18.2.24 DDS LongLong DDS DataReaderProtocolStatus::sent -

nack bytes change

The incremental change in the number of bytes of NACKs sent from a local

DataReader to a matching remote DataWriter since the last time the status

was read.

6.18.2.25 DDS LongLong DDS -

DataReaderProtocolStatus::received gap count

The number of GAPs received from remote DataWriter to this DataReader.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.18 DDS DataReaderProtocolStatus Struct Reference 513

6.18.2.26 DDS LongLong DDS -

DataReaderProtocolStatus::received gap count change

The incremental change in the number of GAPs received from rem ote

DataWriter to this DataReader since the last time the status was read.

6.18.2.27 DDS LongLong DDS -

DataReaderProtocolStatus::received gap bytes

The number of bytes of GAPs rec eived from remote DataWriter to this

DataReader.

6.18.2.28 DDS LongLong DDS -

DataReaderProtocolStatus::received gap bytes change

The incremental change in the number of bytes of GAPs received from remote

DataWriter to this DataReader since the last time the status was read.

6.18.2.29 DDS LongLong DDS -

DataReaderProtocolStatus::rejected sample count

The number of times a sample is rejected due to exceptions in the receive path.

6.18.2.30 DDS LongLong DDS -

DataReaderProtocolStatus::rejected -

sample count change

The incremental change in the number of times a sample is rejected due to

exceptions in the receive path since the last time the status was read.

6.18.2.31 struct DDS SequenceNumber t

DDS DataReaderProtocolStatus::ﬁrst available sample -

sequence number [read]

Sequence number of the ﬁrst available sample in a matched Datawriters relia-

bility queue.

Applicable only for reliable DataReaders, and when retrieving matched

DataWriter statuses.

Updated upon receiving Heartbeat submessages from a matched reliable

DataWriter.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

514 Class Documentation

6.18.2.32 struct DDS SequenceNumber t

DDS DataReaderProtocolStatus::last available sample -

sequence number [read]

Sequence number of the last available sample in a matched Datawriter’s relia-

bility queue.

Applicable only for reliable DataReaders, and when retrieving matched

DataWriter statuses.

Updated upon receiving Heartbeat submessages from a matched reliable

DataWriter.

6.18.2.33 struct DDS SequenceNumber t

DDS DataReaderProtocolStatus::last -

committed sample sequence number

[read]

Sequence number of the newest sample received from the matched DataWriter

committed to the DataReader’s queue.

Applicable only when retrieving matched DataWriter statuses.

For best-eﬀort DataReaders, this is the sequence number of the latest sample

received.

For reliable DataReaders, this is the sequence number of the latest sample that

is available to be read or taken from the DataReader’s queue.

6.18.2.34 DDS Long DDS -

DataReaderProtocolStatus::uncommitted sample count

Number of received samples that are not yet available to be read or taken, due

to being received out of order.

Applicable only when retrieving matched DataWriter statuses.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.19 DDS DataReaderQos Struct Reference 515

6.19 DDS DataReaderQos Struct R efere nce

QoS policies supported by a DDSDataReader (p. 1087) entity.

Public Attributes

struct DDS DurabilityQosPolicy durability

Durability policy, DURABILITY ( p. 348).

struct DDS DeadlineQosPolicy deadline

Deadline policy, DEADLINE ( p. 353).

struct DDS LatencyBudgetQosPolicy latency budget

Latency budget policy, LATENCY BUDGET ( p. 354).

struct DDS LivelinessQosPolicy liveliness

Liveliness policy, LIVELINESS ( p. 358).

struct DDS ReliabilityQosPolicy reliability

Reliability policy, RELIABILITY ( p. 362).

struct DDS DestinationOrderQosPolicy destination order

Destination order policy, DESTINATION ORDER ( p. 365).

struct DDS HistoryQosPolicy history

History policy, HISTORY ( p. 367).

struct DDS ResourceLimitsQosPolicy resource limits

Resource limits policy, RESOURCE LIMITS ( p. 371).

struct DDS UserDataQosPolicy user data

User data policy, USER DATA ( p. 345).

struct DDS OwnershipQosPolicy ownership

Ownership policy, OWNERSHIP ( p. 355).

struct DDS TimeBasedFilterQosPolicy time based ﬁlter

Time-based ﬁlter policy, TIME BASED FILTER ( p. 360).

struct DDS ReaderDataLifecycleQosPolicy reader data -

lifecycle

Reader data lifecycle pol icy, READER DATA LIFECYCLE ( p. 376).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

516 Class Documentation

struct DDS TypeConsistencyEnforcementQosPolicy type -

consistency

Type consistency enforcement policy, TYPE CONSISTENCY -

ENFORCEMENT ( p. 432).

struct DDS DataReaderResourceLimitsQosPolicy reader -

resource limits

<<eXtension>> (p. 199) DDSDataReader ( p. 1087) resource limits pol-

icy, DATA READER RESOURCE LIMITS ( p. 407). This policy is an

extension to the DDS standard.

struct DDS DataReaderProtocolQosPolicy protocol

<<eXtension>> (p. 199) DDSDataReader ( p. 1087) protocol policy,

DATA READER PROTOCOL ( p. 413)

struct DDS TransportSelecti onQosPolicy transport selection

<<eXtension>> (p. 199) Transport selection policy, TRANSPORT -

SELECTION ( p. 382).

struct DDS TransportUnicastQosPolicy unicast

<<eXtension>> (p. 199) Unicast transport policy, TRANSPORT -

UNICAST ( p. 383).

struct DDS TransportMulticastQosPolicy multicast

<<eXtension>> (p. 199) Multicast transport policy, TRANSPORT -

MULTICAST ( p. 384).

struct DDS PropertyQosPolicy property

<<eXtension>> (p. 199) Property policy, PROPERTY ( p. 436).

struct DDS AvailabilityQosPolicy availability

<<eXtension>> (p. 199) Availability policy, AVAILABILITY ( p. 442).

struct DDS EntityNameQosPolicy subscription name

<<eXtension>> (p. 199) EntityName policy, ENTITY NAME ( p. 445).

struct DDS TypeSupportQosPolicy type support

<<eXtension>> (p. 199) type support data, TYPESUPPORT ( p. 429).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.19 DDS DataReaderQos Struct Reference 517

6.19.1 Detailed Description

QoS policies supported by a DDSDataReader (p. 1087) entity.

You must set certain members in a consistent manner:

DDS DataReaderQos::deadline.period >= DDS DataReaderQos::time based -

ﬁlter.minimum separation

DDS DataReaderQos::history.depth <= DDS DataReaderQos::resource -

limits.max samples per instance

DDS DataReaderQos::resource limits.max samples per instance <= DDS -

DataReaderQos::resource limits.max samples DDS DataReaderQos::resource -

limits.initial samples <= DDS DataReaderQos::resource limits.max samples

DDS DataReaderQos::resource limits.initial instances <= DDS -

DataReaderQos::resource limits.max instances

DDS DataReaderQos::reader resource limits.initial remote writers per -

instance <= DDS DataReaderQos::reader resource limits.max remote -

writers per instance

DDS DataReaderQos::reader resource limits.initial infos <= DDS -

DataReaderQos::reader resource limits.max infos

DDS DataReaderQos::reader resource limits.max remote writers per instance

<= DDS DataReaderQos::reader resource limits.max remote writers

DDS DataReaderQos::reader resource limits.max samples pe r remote writer

<= DDS DataReaderQos::resource limits.max samples

length of DDS DataReaderQos::user data.value <= DDS -

DomainParticipantQos::resource limits.reader user data max length

If any of the above are not true, DDSDataReader::set qos (p. 1102)

and DDSDataReader::set qos with proﬁle (p. 1103) will fail with DDS -

RETCODE INCONSISTENT POLICY (p. 315)

6.19.2 Member Data Documentation

6.19.2.1 struct DDS DurabilityQosPolicy

DDS DataReaderQos::durability [read]

Durability policy, DURABILITY (p. 348).

6.19.2.2 struct DDS DeadlineQosPolicy DDS -

DataReaderQos::deadline [read]

Deadline policy, DEADLINE (p. 353).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

518 Class Documentation

6.19.2.3 struct DDS LatencyBudgetQosPol icy

DDS DataReaderQos::latency budget [read]

Latency budget policy, LATENCY BUDGET (p. 354).

6.19.2.4 struct DDS LivelinessQosPolicy

DDS DataReaderQos::liveliness [read]

Liveliness policy, LIVELINESS (p. 358).

6.19.2.5 struct DDS ReliabilityQosPolicy

DDS DataReaderQos::reliability [read]

Reliability policy, RELIABILITY (p. 362).

6.19.2.6 struct DDS DestinationOrderQosPolicy

DDS DataReaderQos::destination order [read]

Destination order policy, DESTINATION ORDER (p. 365).

6.19.2.7 struct DDS HistoryQosPolicy DDS -

DataReaderQos::history [read]

History policy, HISTORY (p. 367).

6.19.2.8 struct DDS ResourceLimitsQosPolicy

DDS DataReaderQos::resource limits [read]

Resource limits policy, RESOURCE LIMITS (p. 371).

6.19.2.9 struct DDS UserDataQosPolicy

DDS DataReaderQos::user data [read]

User data policy, USER DATA (p. 345).

6.19.2.10 struct DDS OwnershipQosPolicy

DDS DataReaderQos::ownership [read]

Ownership policy, OWNERSHIP (p. 355).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.19 DDS DataReaderQos Struct Reference 519

6.19.2.11 struct DDS TimeBasedFilterQosPolicy

DDS DataReaderQos::time based ﬁlter [read]

Time-based ﬁlter policy, TIME BASED FILTER (p. 360).

6.19.2.12 struct DDS ReaderDataLifecycleQosPolicy

DDS DataReaderQos::reader data lifecycle [read]

Reader data lifecycle policy, READER DATA LIFECYCLE (p. 376).

6.19.2.13 struct DDS TypeConsistencyEnforcementQosPolicy

DDS DataReaderQos::type consistency [read]

Type consistency enforcement policy, TYPE CONSISTENCY -

ENFORCEMENT (p. 432).

6.19.2.14 struct DDS DataReaderResourceLimitsQosPolicy

DDS DataReaderQos::reader resource limits [read]

<<eXtension>> ( p. 199) DDSDataReader (p. 1087) resource limits policy,

DATA READER RESOURCE LIMITS (p. 407). This policy is an exten-

sion to the DDS standard.

6.19.2.15 struct DDS DataReaderProtocolQosPolicy

DDS DataReaderQos::protocol [read]

<<eXtension>> ( p. 199) DDSDataReader (p. 1087) protocol policy,

DATA READER PROTOCOL (p. 413)

6.19.2.16 struct DDS TransportSelectionQosPolicy

DDS DataReaderQos::transport selection [read]

<<eXtension>> ( p. 199) Transport selection policy, TRANSPORT -

SELECTION (p. 382).

Speciﬁes the transports available for use by the DDSDataReader (p. 1087).

6.19.2.17 struct DDS TransportUnicastQosPol icy

DDS DataReaderQos::unicast [read]

<<eXtension>> ( p. 199 ) Unicast transport policy, TRANSPORT -

UNICAST (p. 383).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

520 Class Documentation

Speciﬁes the unicast transport interfaces and ports on which messages can be

received.

The unicast interfaces are used to receive messages from DDSDataWriter

(p. 1113) entities in the domain.

6.19.2.18 struct DDS TransportMulticastQosPoli cy

DDS DataReaderQos::multicast [read]

<<eXtension>> ( p. 199) Multicast transport policy, TRANSPORT -

MULTICAST (p. 384).

Speciﬁes the multicast group addresses and ports on which messages can be

received.

The multicast addresses are used to receive messages from DDSDataWriter

(p. 1113) entities in the domain.

6.19.2.19 struct DDS PropertyQosPolicy

DDS DataReaderQos::property [read]

<<eXtension>> ( p. 199) Property policy, PROPERTY (p. 436).

6.19.2.20 struct DDS AvailabilityQosPolicy

DDS DataReaderQos::availability [read]

<<eXtension>> ( p. 199) Availability policy, AVAILABILITY (p. 442).

6.19.2.21 struct DDS EntityNameQosPolicy

DDS DataReaderQos::subscription name [read]

<<eXtension>> ( p. 199) EntityName policy, ENTITY NAME (p. 445).

6.19.2.22 struct DDS TypeSupportQosPolicy

DDS DataReaderQos::type support [read]

<<eXtension>> ( p. 199) type support data, TYPESUPPORT (p. 429).

Optional value that is passed to a type plugin’s on endpoint attached and de-

serialization functions.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.20 DDS DataReaderResourceLimitsQosPoli cy Struct Reference521

6.20 DDS DataReaderResourceLimitsQosPolicy

Struct Reference

Various settings that conﬁgure how a DDSDataReader (p. 1087) allocates and

uses physical memory for internal resources.

Public Attributes

DDS Long max remote writers

The maximum number of remote writers from which a DDSDataReader

( p. 1087) may read, including all instances.

DDS Long max remote writers per instance

The maximum number of remote writers from which a DDSDataReader

( p. 1087) may read a single instance.

DDS Long max samples per remote writer

The maximum number of out-of-order samples from a given remote DDS-

DataWriter ( p. 1113) that a DDSDataReader ( p. 1087) may store when

maintaining a reliable connection to the DDSDataWriter ( p. 1113).

DDS Long max infos

The maximum number of info units that a DDSDataReader ( p. 1087) can

use to store DDS SampleInfo ( p. 912).

DDS Long initial remote writers

The initial number of remote writers from which a DDSDataReader

( p. 1087) may read, including all instances.

DDS Long initial remote writers per instance

The initial number of remote writers from which a DDSDataReader

( p. 1087) may read a single instance.

DDS Long initial infos

The initial number of info units that a DDSDataReader ( p. 1087) can have,

which are used to store DDS SampleInfo ( p. 912).

DDS Long initial outstanding reads

The initial number of outstanding calls to read/take (or one of their variants)

on the same DDSDataReader ( p. 1087) for which memory has not been

returned by calling FooDataReader::return loan ( p. 1471).

DDS Long max outstanding reads

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

522 Class Documentation

The maximum number of outstanding read/take calls (or one of their vari-

ants) on the same DDSDataReader ( p. 1087) for which memory has not

been returned by calling FooDataReader::return loan ( p. 1471).

DDS Long max samples per read

The maximum number of data samples that the application can receive from

the middleware in a single call to FooDataReader::read ( p. 1447) or Foo-

DataReader::take ( p. 1448). If more data exists in the middleware, the

application will need to issue multiple read/take calls.

DDS Boolean disable fragmentation support

Determines whether the DDSDataReader ( p. 1087) can receive fragmented

samples.

DDS Long max fragmented samples

The maximum number of samples for which the DDSDataReader ( p. 1087)

may store fragments at a given point in time.

DDS Long initial fragmented samples

The initial number of samples for which a DDSDataReader ( p. 1087) may

store fragments.

DDS Long max fragmented samples per remote writer

The maximum number of samples per remote writer for which a DDS-

DataReader ( p. 1087) may store fragments.

DDS Long max fragments per sample

Maximum number of fragments for a single sample.

DDS Boolean dynamically allocate fragmented samples

Determines whether the DDSDataReader ( p. 1087) pre-allocates storage

for storing fragmented samples.

DDS Long max total instances

Maximum number of instances for which a DataReader will keep state.

DDS Long max remote virtual writers

The maximum number of remote virtual writers from which a DDS-

DataReader ( p. 1087) may read, including all instances.

DDS Long initial remote virtual writers

The initial number of remote virtual writers from which a DDSDataReader

( p. 1087) may read, including all instances.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.20 DDS DataReaderResourceLimitsQosPoli cy Struct Reference523

DDS Long max remote virtual writers per instance

The maximum number of virtual remote writers that can be associated with

an instance.

DDS Long initial remote virtual writers per instance

The initial number of virtual remote writers per instance.

DDS Long max remote writers per sample

The maximum number of remote writers allowed to write the same sample.

DDS Long max query condition ﬁlters

The maximum number of query condition ﬁlters a reader is allowed.

DDS Long max app ack response length

Maximum length of application-level acknowledgment response data.

6.20.1 Detailed Description

Various settings that conﬁgure how a DDSDataReader (p. 1087) allocates and

uses physical memory for internal resources.

DataReaders must allocate internal structures to handle the maximum number

of DataWriters that may connect to it, whether or not a DDSDataReader

(p. 1087) handles data fragmentation and how many data fragments that it may

handle (for data samples larger than the MTU of the underlying network trans-

port), how many simultaneous outstanding loans of internal memory holding

data samples can be provided to user code, as well as others.

Most of these internal structures start at an initial size and, by default, will

grow as needed by dynamically allocating additional memory. You may set

ﬁxed, maximum sizes for these internal structures if you want to bound the

amount of memory that can be used by a DDSDataReader (p. 1087). By

setting the initial size to the maximum size, you will prevent RTI Connext from

dynamically allocating any memory after the creation of the DDSDataReader

(p. 1087).

This QoS policy is an extension to the DDS standard.

Entity:

DDSDataReader (p. 1087)

Properties:

RxO (p. 340) = N/A

Changeable (p. 340) = NO (p. 340)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

524 Class Documentation

6.20.2 Member Data Documentation

6.20.2.1 DDS Long DDS -

DataReaderResourceLimitsQosPolicy::max remote writers

The maximum number of remote writers from which a DDSDataReader

(p. 1087) may read, including all instances.

[default] DDS LENGTH UNLIMITED (p. 371)

[range] [1, 1 million] or DDS LENGTH UNLIMITED (p. 371), >= initial -

remote

writers, >= max remote writers per instance

For unkeyed types, this value has to be equal to max remote writers per -

instance if max remote writers per instance is not equal to DDS LENGTH -

UNLIMITED (p. 371).

Note: For eﬃciency, set max remote writers >= DDS -

DataReaderResourceLimitsQosPolicy::max remote writers per -

instance (p. 524).

6.20.2.2 DDS Long DDS -

DataReaderResourceLimitsQosPolicy::max -

remote writers per instance

The maximum number of remote writers from which a DDSDataReader

(p. 1087) may read a single instance.

[default] DDS LENGTH UNLIMITED (p. 371)

[range] [1, 1024] or DDS LENGTH UNLIMITED (p. 371), <= max -

remote writers or DDS LENGTH UNLIMITED (p. 371), >= initial -

remote writers per instance

For unkeyed types, this value has to be equal to max remote writers if it is not

DDS LENGTH UNLIMITED (p. 371).

Note: For eﬃciency, set max remote writers per instance <= DDS -

DataReaderResourceLimitsQosPolicy::max remote writers (p. 524)

6.20.2.3 DDS Long DDS -

DataReaderResourceLimitsQosPolicy::max -

samples per remote writer

The maximum number of out-of-order samples from a given remote DDS-

DataWriter (p. 1113) that a DDSDataReader (p. 1087) may store when

maintaining a reliable connection to the DDSDataWriter (p. 1113).

[default] DDS LENGTH UNLIMITED (p. 371)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.20 DDS DataReaderResourceLimitsQosPoli cy Struct Reference525

[range] [1, 100 million] or DDS LENGTH UNLIMITED (p. 371), <=

DDS ResourceLimitsQosPolicy::max samples (p. 881)

6.20.2.4 DDS Long DDS -

DataReaderResourceLimitsQosPolicy::max infos

The maximum number of info units that a DDSDataReader (p. 1087) can use

to store DDS SampleInfo (p. 912).

When read/take is called on a DataReader, the DataReader passes a sequence of

data samples and an associated sample info sequence. The sample info sequence

contains additional information for each data sample.

max infos determines the resources allocated for storing sample info. This mem-

ory is loaned to the application when passing a sample info sequence.

Note that sample info is a snapshot, generated when read/take is called.

max infos should not be less than max samples.

[default] DDS LENGTH UNLIMITED (p. 371)

[range] [1, 1 million] or DDS LENGTH UNLIMITED (p. 371), >= initial -

infos

6.20.2.5 DDS Long DDS -

DataReaderResourceLimitsQosPolicy::initial remote -

writers

The initial number of remote writers from which a DDSDataReader (p. 1087)

may read, including all instances.

[default] 2

[range] [1, 1 million], <= max remote writers

For unkeyed types this value has to be equal to initial remote writers per -

instance.

Note: For eﬃciency, set initial remote writers >= DDS -

DataReaderResourceLimitsQosPolicy::initial remote writers per -

instance (p. 525).

6.20.2.6 DDS Long DDS -

DataReaderResourceLimitsQosPolicy::initial remote -

writers per instance

The initial number of remote writers from which a DDSDataReader (p. 1087)

may read a single instance.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

526 Class Documentation

[default] 2

[range] [1,1024], <= max remote writers pe r instance

For unkeyed types this value has to be equal to initial remote writers.

Note: For eﬃciency, set initial remote writers per instance <= DDS -

DataReaderResourceLimitsQosPolicy::initial remote writers (p. 525).

6.20.2.7 DDS Long DDS -

DataReaderResourceLimitsQosPolicy::initial infos

The initial number of info units that a DDSDataReader (p. 1087) can have,

which are used to store DDS SampleInfo (p. 912).

[default] 32

[range] [1,1 million], <= max infos

6.20.2.8 DDS Long DDS -

DataReaderResourceLimitsQosPolicy::initial outstanding -

reads

The initial number of outstanding calls to read/take (or one of their variants) on

the same DDSDataReader (p. 1087) for which memory has not been returned

by calling FooDataReader::return loan (p. 1471).

[default] 2

[range] [1, 65536], <= max outstanding reads

6.20.2.9 DDS Long DDS -

DataReaderResourceLimitsQosPolicy::max -

outstanding reads

The maximum number of outstanding read/take calls (or one of their variants)

on the same DDSDataReader (p. 1087) for which memory has not been re-

turned by calling FooDataReader::return loan (p. 1471).

[default] DDS LENGTH UNLIMITED (p. 371)

[range] [1, 65536] or DDS LENGTH UNLIMITED (p. 371), >= initial -

outstanding reads

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.20 DDS DataReaderResourceLimitsQosPoli cy Struct Reference527

6.20.2.10 DDS Long DDS -

DataReaderResourceLimitsQosPolicy::max samples per -

read

The maximum number of data samples that the application can receive from

the middleware in a single call to FooDataReader::read (p. 1447) or Foo-

DataReader::take (p. 1448). If more data exists in the middleware, the appli-

cation will need to issue multiple read/take calls.

When reading data using listeners, the expected number of samples available

for delivery in a single take call is typically small: usually just one, in the

case of unbatched data, or the number of samples in a single batch, in the case

of batched data. (See DDS BatchQosPolicy (p. 476) for more information

about this feature.) When p olling for data or using a DDSWaitSet (p. 1433),

however, multiple samples (or batches) could be retrieved at once, depending

on the data rate.

A larger value for this parameter makes the API simpler to use at the expense

of some additional memory consumption.

[default] 1024

[range] [1,65536]

6.20.2.11 DDS Boolean DDS -

DataReaderResourceLimitsQosPolicy::disable -

fragmentation support

Determines whether the DDSDataReader (p. 1087) can receive fragmented

samples.

When fragmentation support is not needed, disabling fragmentation support

will save some memory resources.

[default] DDS BOOLEAN FALSE (p. 299)

6.20.2.12 DDS Long DDS -

DataReaderResourceLimitsQosPolicy::max fragmented -

samples

The maximum number of samples for which the DDSDataReader (p. 1087)

may store fragments at a given point in time.

At any given time, a DDSDataReader (p. 1087) may store fragments for up to

max fragmented samples samples while waiting for the remaining fragments.

These samples need not have consecutive sequence numbers and may have been

sent by diﬀerent DDSDataWriter (p. 1113) instances.

Once all fragments of a sample have been received, the sample is treated as a

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

528 Class Documentation

regular sample and becomes subject to standard QoS settings such as DDS -

ResourceLimitsQosPolicy::max samples (p. 881).

The middleware will drop fragments if the max fragmented samples limit has

been reached. For best-eﬀort communication, the middleware will accept a

fragment for a new sample, but drop the oldest fragmented sample from the

same remote writer. For reliable communication, the middleware will drop

fragments for any new samples until all fragments for at least one older sample

from that writer have been received.

Only applies if DDS DataReaderResourceLimitsQosPolicy::disable -

fragmentation support (p. 527) is DDS BOOLEAN FALSE (p. 299).

[default] 1024

[range] [1, 1 million]

6.20.2.13 DDS Long DDS -

DataReaderResourceLimitsQosPolicy::initial -

fragmented samples

The initial number of samples for which a DDSDataReader (p. 1087) may

store fragments.

Only applies if DDS DataReaderResourceLimitsQosPolicy::disable -

fragmentation support (p. 527) is DDS BOOLEAN FALSE (p. 299).

[default] 4

[range] [1,1024], <= max fragmented samples

6.20.2.14 DDS Long DDS -

DataReaderResourceLimitsQosPolicy::max fragmented -

samples per remote writer

The maximum number of samples per remote writer for which a DDS-

DataReader (p. 1087) may store fragments.

Logical limit so a single remote writer cannot consume all available resources.

Only applies if DDS DataReaderResourceLimitsQosPolicy::disable -

fragmentation support (p. 527) is DDS BOOLEAN FALSE (p. 299).

[default] 256

[range] [1, 1 million], <= max fragmented samples

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.20 DDS DataReaderResourceLimitsQosPoli cy Struct Reference529

6.20.2.15 DDS Long DDS -

DataReaderResourceLimitsQosPolicy::max fragments -

per sample

Maximum number of fragments for a single sample.

Only applies if DDS DataReaderResourceLimitsQosPolicy::disable -

fragmentation support (p. 527) is DDS BOOLEAN FALSE (p. 299).

[default] 512

[range] [1, 1 million] or DDS LENGTH UNLIMITED (p. 371)

6.20.2.16 DDS Boolean DDS -

DataReaderResourceLimitsQosPolicy::dynamically -

allocate fragmented samples

Determines whether the DDSDataReader (p. 1087) pre-allocates storage for

storing fragmented samples.

By default, the middleware will allocate memory upfront for storing frag-

ments for up to DDS DataReaderResourceLimitsQosPolicy::initial -

fragmented samples (p. 528) samples. This me mory may grow up to DDS -

DataReaderResourceLimitsQosPolicy::max fragmented samples

(p. 527) if needed.

If dynamically allocate fragmented samples is set to DDS BOOLEAN -

TRUE (p. 298), the middleware does not allocate memory upfront, but instead

allocates memory from the heap upon receiving the ﬁrst fragment of a new

sample. The amount of memory allocated equals the amount of memory needed

to store all fragments in the sample. Once all fragments of a sample have been

received, the sample is deserialized and stored in the regular receive queue. At

that time, the dynamically allocated memory is freed again.

This QoS setting may be useful for large, but variable-sized data types where

upfront memory allocation for multiple samples based on the maximum possible

sample size may be expensive. The main disadvantage of not pre-allocating

memory is that one can no longer guarantee the middleware will have suﬃcient

resources at run-time.

Only applies if DDS DataReaderResourceLimitsQosPolicy::disable -

fragmentation support (p. 527) is DDS BOOLEAN FALSE (p. 299).

[default] DDS BOOLEAN FALSE (p. 299)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

530 Class Documentation

6.20.2.17 DDS Long DDS -

DataReaderResourceLimitsQosPolicy::max total -

instances

Maximum number of instances for which a DataReader will keep state.

The maximum number of instances actively managed by a DataReader is de-

termined by DDS ResourceLimitsQosPolicy::max instances (p. 882).

These instances have associated DataWriters or samples in the DataReader’s

queue and are visible to the user through operations such as Foo-

DataReader::take (p. 1448), FooDataReader::read (p. 1447), and Foo-

DataReader::get key value (p. 1472).

The features Durable Reader State, MultiChannel DataWriters and RTI Persis-

tence Service require RTI Connext to keep some internal state even for instances

without DataWriters or samples in the DataReader’s queue. The additional

state is use d to ﬁlter duplicate samples that could be coming from diﬀerent

DataWriter channels or from multiple executions of RTI Persistence Service.

The total maximum number of instances that will be managed by the middle-

ware, including instances without associated DataWriters or samples, is deter-

mined by max total instances.

When a new instance is received, RTI Connext will check the resource limit

DDS ResourceLimitsQosPolicy::max instances (p. 882). If the limit is

exceeded, RTI Connext will drop the sample and report it as lost and rejected.

If the limit is not exceeded, RTI Connext will check max total instances. If

max total instances is exceeded, RTI Connext will replace an existing instance

without DataWriters and samples with the new one. The application could

receive duplicate samples for the replaced instance if it becomes alive again.

[default] DDS AUTO MAX TOTAL INSTANCES (p. 408)

[range] [1, 1 million] or DDS LENGTH UNLIMITED (p. 371) or

DDS AUTO MAX TOTAL INSTANCES (p. 408), >= DDS -

ResourceLimitsQosPolicy::max instances (p. 882)

6.20.2.18 DDS Long DDS -

DataReaderResourceLimitsQosPolicy::max remote -

virtual writers

The maximum number of remote virtual writers from which a DDS-

DataReader (p. 1087) may read, including all instances.

When DDS PresentationQosPolicy::access scop e (p. 826) is set to DDS -

GROUP PRESENTATION QOS (p. 352), this value determines the max-

imum number of DataWriter groups that can be managed by the DDSSub-

scriber (p. 1390) containing this DDSDataReader (p. 1087).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.20 DDS DataReaderResourceLimitsQosPoli cy Struct Reference531

Since the DDSSubscriber (p. 1390) may contain more than one DDS-

DataReader (p. 1087), only the setting of the ﬁrst applies.

[default] DDS LENGTH UNLIMITED (p. 371)

[range] [1, 1 million] or DDS LENGTH UNLIMITED (p. 371), >= initial -

remote virtual writers, >= max remote virtual writers per instance

6.20.2.19 DDS Long DDS -

DataReaderResourceLimitsQosPolicy::initial remote -

virtual writers

The initial number of remote virtual writers from which a DDSDataReader

(p. 1087) may read, including all instances.

[default] 2

[range] [1, 1 million] or DDS LENGTH UNLIMITED (p. 371), <= max -

remote virtual writers

6.20.2.20 DDS Long DDS -

DataReaderResourceLimitsQosPolicy::max remote -

virtual writers per instance

The maximum number of virtual remote writers that can be associated with an

instance.

[default] DDS LENGTH UNLIMITED (p. 371)

[range] [1, 1024] or DDS LENGTH UNLIMITED (p. 371), >= initial -

remote virtual writers per instance

For unkeyed types, this value is ignored.

The features of Durable Reader State and MultiChannel DataWriters, and RTI

Persistence Service require RTI Connext to keep some internal state per virtual

writer and instance that is used to ﬁlter duplicate samples. These duplicate

samples could be coming from diﬀerent DataWriter channels or from multiple

executions of RTI Persistence Service.

Once an association between a remote virtual writer and an instance is es-

tablished, it is permanent – it will not disappear even if the physical writer

incarnating the virtual writer is destroyed.

If max remote virtual writers per instance is e xcee ded for an instance, RTI

Connext will not associate this instance with new virtual writers. Duplicates

samples from these virtual writers will not be ﬁltered on the reader.

If you are not using Durable Reader State, MultiChannel DataWriters or RTI

Persistence Service in your system, you can set this property to 1 to optimize

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

532 Class Documentation

resources.

6.20.2.21 DDS Long DDS -

DataReaderResourceLimitsQosPolicy::initial remote -

virtual writers per instance

The initial number of virtual remote writers per instance.

[default] 2

[range] [1, 1024], <= max remote virtual writers per instance

For unkeyed types, this value is ignored.

6.20.2.22 DDS Long DDS -

DataReaderResourceLimitsQosPolicy::max remote -

writers per sample

The maximum number of remote writers allowed to write the same sample.

One scenario in w hich two DataWriters may write the same sample is Persistence

Service. The DataReader may receive the same sample coming from the original

DataWriter and from a Persistence Service DataWriter. [default] 3

[range] [1, 1024]

6.20.2.23 DDS Long DDS -

DataReaderResourceLimitsQosPolicy::max query -

condition ﬁlters

The maximum number of query condition ﬁlters a reader is allowed.

[default] 4

[range] [0, 32]

This value determines the maximum number of unique query condition content

ﬁlters that a reader may create.

Each query condition content ﬁlter is comprised of both its query expression

and query parameters. Two query conditions that have the same query -

expression will require unique query condition ﬁlters if their query paramters

diﬀer. Query conditions that diﬀer only in their state masks will share the same

query condition ﬁlter.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.20 DDS DataReaderResourceLimitsQosPoli cy Struct Reference533

6.20.2.24 DDS Long DDS -

DataReaderResourceLimitsQosPolicy::max app ack -

response length

Maximum length of application-level acknowledgment response data.

The maximum length of res ponse data in an application-level acknowledgment.

When set to zero, no response data is sent with application-level acknowledg-

ments.

[default] 0

[range] [0, 65536]

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

534 Class Documentation

6.21 DDS DataWriterCacheStatus Struct Ref-

erence

<<eXtension>> ( p. 199) The status of the writer’s cache.

Public Attributes

DDS LongLong sample count peak

Highest number of samples in the writer’s queue over the lifetime of the

writer.

DDS LongLong sample count

Number of samples in the writer’s queue.

6.21.1 Detailed Description

<<eXtension>> ( p. 199) The status of the writer’s cache.

Entity:

DDSDataWriter (p. 1113)

6.21.2 Member Data Documentation

6.21.2.1 DDS LongLong DDS DataWriterCacheStatus::sample -

count peak

Highest number of samples in the writer’s queue over the lifetime of the writer.

6.21.2.2 DDS LongLong DDS DataWriterCacheStatus::sample -

count

Number of samples in the writer’s queue.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.22 DDS DataWriterProtocolQosPolicy Struct Reference 535

6.22 DDS DataWriterProtocolQosPolicy Struct

Reference

Protocol that applies only to DDSDataWriter (p. 1113) instances.

Public Attributes

struct DDS GUID t virtual guid

The virtual GUID (Global Unique Identiﬁer).

DDS UnsignedLong rtps object id

The RTPS Object ID.

DDS Boolean push on write

Whether to push sample out when write is called.

DDS Boolean disable positive acks

Controls whether or not the writer expects positive acknowledgements from

matching readers.

DDS Boolean disable inline keyhash

Controls whether or not a keyhash is propagated on the wire with each sample.

DDS Boolean serialize key with dispose

Controls whether or not the serialized key is propagated on the wire with

dispose samples.

struct DDS RtpsReliableWriterProtocol t rtps reliable writer

The reliable protocol deﬁned in RTPS.

6.22.1 Detailed Description

Protocol that applies only to DDSDataWriter (p. 1113) instances.

DDS has a standard protocol for packet (user and meta data) exchange between

applications using DDS for communications. This QoS p olicy and DDS -

DataWriterProtocolQosPolicy (p. 535) give you control over conﬁgurable

portions of the protocol, including the conﬁguration of the reliable data deliv-

ery mechanism of the protocol on a per DataWriter or DataReader basis.

These conﬁguration parameters control timing, timeouts, and give you the abil-

ity to tradeoﬀ between spee d of data loss detection and repair versus network

and C PU bandwidth use d to maintain reliability.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

536 Class Documentation

It is important to tune the reliability protocol (on a per DDSDataWriter

(p. 1113) and DDSDataReader (p. 1087) basis) to meet the requirements of

the end-user application so that data can be sent between DataWriters and

DataReaders in an eﬃcient and optimal manner in the presence of data loss.

You can also use this QoS policy to control how RTI Connext responds to

”slow” reliable DataReaders or ones that disconnect or are otherwise lost.

See DDS ReliabilityQosPolicy (p. 865) for more information on the per-

DataReader/DataWriter reliability conﬁguration. DDS HistoryQosPolicy

(p. 758) and DDS ResourceLimitsQosPolicy (p. 879) also play an impor-

tant role in the DDS reliable protocol.

This QoS policy is an extension to the DDS standard.

Entity:

DDSDataWriter (p. 1113)

Properties:

RxO (p. 340) = N/A

Changeable (p. 340) = NO (p. 340)

6.22.2 Member Data Documentation

6.22.2.1 struct DDS GUID t DDS -

DataWriterProtocolQosPolicy::virtual guid

[read]

The virtual GUID (Global Unique Identiﬁer).

The virtual GUID is used to uniquely identify diﬀerent incarnations of the same

DDSDataWriter (p. 1113).

RTI Connext uses the virtual GUID to associate a persisted writer history to a

speciﬁc DDSDataWriter (p. 1113).

The RTI Connext Persistence Service uses the virtual GUID to send samples

on behalf of the original DDSDataWriter (p. 1113).

[default] DDS GUID AUTO (p. 309)

6.22.2.2 DDS UnsignedLong DDS -

DataWriterProtocolQosPolicy::rtps object id

The RTPS Object ID.

This value is used to determine the RTPS object ID of a data writer according

to the DDS-RTPS Interoperability Wire Protoc ol.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.22 DDS DataWriterProtocolQosPolicy Struct Reference 537

Only the last 3 bytes are used; the most signiﬁcant byte is ignored.

If the default value is speciﬁed, RTI Connext will automatically assign the object

ID based on a counter value (per participant) starting at 0x00800000. That

value is incremented for each new data writer.

A rtps object id value in the interval [0x00800000,0x00ﬀﬀﬀ] may collide with the

automatic values assigned by RTI Connext. In those cases, the recomendation

is not to use automatic object ID assigment.

[default] DDS RTPS AUTO ID (p. ??)

[range] [0,0x00ﬀﬀﬀ]

6.22.2.3 DDS Boolean DDS DataWriterProtocolQosPolicy::push -

on write

Whether to push sample out when write is called.

If set to DDS BOOLEAN TRUE (p. 298) (the default), the writer will send

a sample every time write is called. Otherwise, the sample is put into the queue

waiting for a NACK from remote reader(s) to be sent out.

[default] DDS BOOLEAN TRUE (p. 298)

6.22.2.4 DDS Boolean DDS -

DataWriterProtocolQosPolicy::disable positive acks

Controls whether or not the writer e xpects positive acknowledgements from

matching readers.

If set to DDS BOOLEAN TRUE (p. 298), the writer does not expect readers

to send send positive acknowledgments to the writer. Consequently, instead of

keeping a sample queued until all readers have positively acknowledged it, the

writer will keep a sample for at least DDS RtpsReliableWriterProtocol -

t::disable positive acks min sample keep duration (p. 898), after which

the sample is logically considered as positively acknowledged.

If set to DDS BOOLEAN FALSE (p. 299) (the default), the writer expects

to receive positive acknowledgements from its acknowledging readers (DDS -

DataReaderProtocolQosPolicy::disable positive acks (p. 503) = DDS -

BOOLEAN FALSE (p. 299)) and it applies the keep-duration to its non-

acknowledging readers (DDS DataReaderProtocolQosPolicy::disable -

positive acks (p. 503) = DDS BOOLEAN TRUE (p. 298)).

A writer with b oth acknowledging and non-acknowledging readers keeps a sam-

ple queued until acknowledgements have been received from all acknowledging

readers and the keep-duration has elapsed for non-acknowledging readers.

[default] DDS BOOLEAN FALSE (p. 299)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

538 Class Documentation

6.22.2.5 DDS Boolean DDS -

DataWriterProtocolQosPolicy::disable inline keyhash

Controls whether or not a keyhash is propagated on the wire with each sample.

This ﬁeld only applies to keyed writers.

With each key, RTI Connext associates an internal 16-byte representation, called

a keyhash.

When this ﬁeld is DDS BOOLEAN FALSE (p. 299), the keyhash is sent on

the wire with every data instance.

When this ﬁeld is DDS BOOLEAN TRUE (p. 298), the keyhash is not sent

on the wire and the readers must compute the value using the received data.

If the reader is CPU b ound, sending the keyhash on the wire may increase

performance, because the reader does not have to get the keyhash from the

data.

If the writer is CPU bound, sending the keyhash on the wire may decrease

performance, because it requires more bandwidth (16 more bytes per sample).

Note: Setting disable inline keyhash to DDS BOOLEAN TRUE (p. 298) is

not compatible with using RTI Real-Time Connect or RTI Recorder.

[default] DDS BOOLEAN FALSE (p. 299)

6.22.2.6 DDS Boolean DDS -

DataWriterProtocolQosPolicy::serialize key with dispose

Controls whether or not the serialized key is propagated on the wire with dispose

samples.

This ﬁeld only applies to keyed writers.

We recommend setting this ﬁeld to DDS BOOLEAN -

TRUE (p. 298) if there are DataReaders where DDS -

DataReaderProtocolQosPolicy::propagate dispose of unregistered -

instances (p. 504) is also DDS BOOLEAN TRUE (p. 298).

Important: When this ﬁeld is DDS BOOLEAN TRUE (p. 298), batching will

not be compatible with RTI Connext 4.3e, 4.4b, or 4.4c. The DDSDataReader

(p. 1087) entities will receive incorrect data and/or encounter deserialization

errors.

[default] DDS BOOLEAN FALSE (p. 299)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.22 DDS DataWriterProtocolQosPolicy Struct Reference 539

6.22.2.7 struct DDS RtpsReliableWriterProtocol t

DDS DataWriterProtocolQosPolicy::rtps reliable writer

[read]

The reliable protocol deﬁned in RTPS.

[default] low watermark 0;

high watermark 1;

heartbeat period 3.0 seconds;

fast heartbeat period 3.0 seconds;

late joiner heartbeat period 3.0 seconds;

virtual heartbeat period DDS DURATION AUTO (p. 305);

samples per virtual heartbeat DDS LENGTH UNLIMITED (p. 371);

max heartbeat retries 10;

inactivate nonprogressing readers DDS BOOLEAN FALSE (p. 299);

heartbeats per max samples 8;

min nack response delay 0.0 seconds;

max nack response delay 0.2 seconds;

max bytes per nack response 131072

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

540 Class Documentation

6.23 DDS DataWriterProtocolStatus Struct

Reference

<<eXtension>> ( p. 199) The status of a writer’s internal protocol related

metrics, like the number of samples pushed, pulled, ﬁltered; and status of wire

protocol traﬃc.

Public Attributes

DDS LongLong pushed sample count

The number of user samples pushed on write from a local DataWriter to a

matching remote DataReader.

DDS LongLong pushed sample count change

The incremental change in the number of user samples pushed on write from

a local DataWriter to a matching remote DataReader since the last time the

status was read.

DDS LongLong pushed sample bytes

The number of bytes of user samples pushed on write from a local DataWriter

to a matching remote DataReader.

DDS LongLong pushed sample bytes change

The incremental change in the number of bytes of user samples pushed on

write from a local DataWriter to a matching remote DataReader since the

last time the status was read.

DDS LongLong ﬁltered sample count

The number of user samples preemptively ﬁltered by a local DataWriter due

to Content-Filtered Topics.

DDS LongLong ﬁltered sample count change

The incremental change in the number of user samples preemptively ﬁltered

by a local DataWriter due to Content-Filtered Topics since the last time the

status was read.

DDS LongLong ﬁltered sample bytes

The number of user samples preemptively ﬁltered by a local DataWriter due

to Content-Filtered Topics.

DDS LongLong ﬁltered sample bytes change

The incremental change in the number of user samples preemptively ﬁltered

by a local DataWriter due to Content-Filtered Topics since the last time the

status was read.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.23 DDS DataWriterProtocolStatus Struct Reference 541

DDS LongLong sent heartbeat count

The number of Heartbeats sent between a local DataWriter and matching

remote DataReader.

DDS LongLong sent heartbeat count change

The incremental change in the number of Heartbeats sent between a local

DataWriter and matching remote DataReader since the last time the status

was read.

DDS LongLong sent heartbeat bytes

The number of bytes of Heartbeats sent between a local DataWriter and

matching remote DataReader.

DDS LongLong sent heartbeat bytes change

The incremental change in the number of bytes of Heartbeats sent between

a local DataWriter and matching remote DataReader since the last time the

status was read.

DDS LongLong pulled sample count

The number of user samples pulled from local DataWriter by matching

DataReaders.

DDS LongLong pulled sample count change

The incremental change in the number of user samples pulled from local

DataWriter by matching DataReaders since the last time the status was read.

DDS LongLong pulled sample bytes

The number of bytes of user samples pulled from local DataWriter by match-

ing DataReaders.

DDS LongLong pulled sample bytes change

The incremental change in the number of bytes of user samples pulled from

local DataWriter by matching DataReaders since the last time the status was

read.

DDS LongLong received ack count

The number of ACKs from a remote DataReader received by a local

DataWriter.

DDS LongLong received ack count change

The incremental change in the numbe r of ACKs from a remote DataReader

received by a local DataWriter since the last time the status was read.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

542 Class Documentation

DDS LongLong received ack bytes

The number of bytes of ACKs from a remote DataReader received by a local

DataWriter.

DDS LongLong received ack bytes change

The incremental change in the number of bytes of ACKs from a remote

DataReader received by a local DataWriter since the last time the status was

read.

DDS LongLong received nack count

The number of NACKs from a remote DataReader received by a local

DataWriter.

DDS LongLong received nack count change

The incremental change in the number of NACKs from a remote DataReader

received by a local DataWriter since the last time the status was read.

DDS LongLong received nack bytes

The number of bytes of NACKs from a remote DataReader received by a local

DataWriter.

DDS LongLong received nack bytes change

The incremental change in the number of bytes of NACKs from a remote

DataReader received by a local DataWriter since the last time the status was

read.

DDS LongLong sent gap count

The number of GAPs sent from local DataWriter to matching re mote

DataReaders.

DDS LongLong sent gap count change

The incremental change in the number of GAPs sent from local DataWriter

to matching remote DataReaders since the last time the status was read.

DDS LongLong sent gap bytes

The number of bytes of GAPs sent from local DataWriter to matching remote

DataReaders.

DDS LongLong sent gap bytes change

The incremental change in the number of bytes of GAPs sent from local

DataWriter to matching remote DataReaders since the last time the status

was read.

DDS LongLong rejected sample count

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.23 DDS DataWriterProtocolStatus Struct Reference 543

The number of times a sample is rejected due to exceptions in the send path.

DDS LongLong rejected sample count change

The incremental change in the number of times a sample is rejected due to

exceptions in the send path since the last time the status was read.

DDS Long send window size

Current maximum number of outstanding samples allowed in the

DataWriter’s queue.

struct DDS SequenceNumber t ﬁrst available sample sequence -

number

The sequence number of the ﬁrst available sample currently queued in the

local DataWriter.

struct DDS SequenceNumber t last available sample sequence -

number

The sequence number of the last available sample currently queued in the

local DataWriter.

struct DDS SequenceNumber t ﬁrst unacknowledged sample -

sequence number

The sequence number of the ﬁrst unacknowledged sample currently queued in

the local DataWriter.

struct DDS SequenceNumber t ﬁrst available sample virtual -

sequence number

The virtual sequence number of the ﬁrst available sample currently queued in

the local DataWriter.

struct DDS SequenceNumber t last available sample virtual -

sequence number

The virtual sequence number of the last available sample currently queued in

the local DataWriter.

struct DDS SequenceNumber t ﬁrst unacknowledged sample -

virtual sequence number

The virtual sequence number of the ﬁrst unacknowledged sample currently

queued in the local DataWriter.

DDS InstanceHandle t ﬁrst unacknowledged sample -

subscription handle

The handle of a remote DataReader that has not acknowledged the ﬁrst un-

acknowledged sample of the local DataWriter.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

544 Class Documentation

struct DDS SequenceNumber t ﬁrst unelapsed keep duration -

sample sequence number

The sequence number of the ﬁrst sample whose keep duration has not yet

elapsed.

6.23.1 Detailed Description

<<eXtension>> ( p. 199) The status of a writer’s internal protocol related

metrics, like the number of samples pushed, pulled, ﬁltered; and status of wire

protocol traﬃc.

Entity:

DDSDataWriter (p. 1113)

6.23.2 Member Data Documentation

6.23.2.1 DDS LongLong DDS DataWriterProtocolStatus::pushed -

sample count

The number of user samples pushed on write from a local DataWriter to a

matching remote DataReader.

Counts protocol (RTPS) messages pushed by a DataWriter when writing, un-

registering, and disposing. The count is the number of sends done internally,

and it may be greater than the number of user writes.

For large data, counts whole samples, not fragments.

6.23.2.2 DDS LongLong DDS DataWriterProtocolStatus::pushed -

sample count change

The incremental change in the number of user samples pushed on write from

a local DataWriter to a matching remote DataReader since the last time the

status was read.

Counts protocol (RTPS) messages pushed by a DataWriter when writing, un-

registering, and disposing.

For large data, counts whole samples, not fragments.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.23 DDS DataWriterProtocolStatus Struct Reference 545

6.23.2.3 DDS LongLong DDS DataWriterProtocolStatus::pushed -

sample bytes

The number of bytes of user samples pushed on write from a local DataWriter

to a matching remote DataReader.

Counts bytes of protocol (RTPS) messages pushed by a DataWriter when writ-

ing, unregistering, and disposing. The count of bytes corresponds to the number

of sends done internally, and it may be greater than the number of user writes.

For large data, counts bytes of whole samples, not fragments.

6.23.2.4 DDS LongLong DDS DataWriterProtocolStatus::pushed -

sample bytes change

The incremental change in the number of bytes of user samples pushed on write

from a local DataWriter to a matching remote DataReader since the last time

the status was read.

Counts bytes of protocol (RTPS) messages pushed by a DataWriter when writ-

ing, unregistering, and disposing.

For large data, counts bytes of whole samples, not fragments.

6.23.2.5 DDS LongLong DDS DataWriterProtocolStatus::ﬁltered -

sample count

The number of user samples preemptively ﬁltered by a local DataWriter due to

Content-Filtered Topics.

6.23.2.6 DDS LongLong DDS DataWriterProtocolStatus::ﬁltered -

sample count change

The incremental change in the number of user samples preemptively ﬁltered by

a local DataWriter due to Content-Filtered Topics since the last time the status

was read.

6.23.2.7 DDS LongLong DDS DataWriterProtocolStatus::ﬁltered -

sample bytes

The number of user samples preemptively ﬁltered by a local DataWriter due to

Content-Filtered Topics.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

546 Class Documentation

6.23.2.8 DDS LongLong DDS DataWriterProtocolStatus::ﬁltered -

sample bytes change

The incremental change in the number of user samples preemptively ﬁltered by

a local DataWriter due to Content-Filtered Topics since the last time the status

was read.

6.23.2.9 DDS LongLong DDS DataWriterProtocolStatus::sent -

heartbeat count

The number of Heartbeats sent between a local DataWriter and matching re-

mote DataReader.

Because periodic and piggyback heartbeats are sent to remote readers and their

locators diﬀerently in diﬀerent situations, when a reader has more than one loca-

tor, this count may be larger than expected, to reﬂect the sending of Heartbeats

to the multiple locators.

6.23.2.10 DDS LongLong DDS DataWriterProtocolStatus::sent -

heartbeat count change

The incremental change in the number of Heartbeats sent between a local

DataWriter and matching remote DataReader since the last time the status

was read.

6.23.2.11 DDS LongLong DDS DataWriterProtocolStatus::sent -

heartbeat bytes

The number of bytes of Heartbeats sent between a local DataWriter and match-

ing remote DataReader.

Because periodic and piggyback heartbeats are sent to remote readers and their

locators diﬀerently in diﬀerent situations, when a reader has more than one loca-

tor, this count may be larger than expected, to reﬂect the sending of Heartbeats

to the multiple locators.

6.23.2.12 DDS LongLong DDS DataWriterProtocolStatus::sent -

heartbeat bytes change

The incremental change in the number of bytes of Heartbeats sent between

a local DataWriter and matching remote DataReader since the last time the

status was read.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.23 DDS DataWriterProtocolStatus Struct Reference 547

6.23.2.13 DDS LongLong DDS DataWriterProtocolStatus::pulled -

sample count

The number of user samples pulled from local DataWriter by matching

DataReaders.

Pulled samples are samples sent for repairs, for late joiners,

and all samples sent by the local DataWriter when DDS -

DataWriterProtocolQosPolicy::push on write (p. 537) is DDS -

BOOLEAN FALSE (p. 299).

For large data, counts whole samples, not fragments.

6.23.2.14 DDS LongLong DDS DataWriterProtocolStatus::pulled -

sample count change

The incremental change in the number of user samples pulled from local

DataWriter by matching DataReaders since the last time the status was read.

Pulled samples are samples sent for repairs, for late joiners,

and all samples sent by the local DataWriter when DDS -

DataWriterProtocolQosPolicy::push on write (p. 537) is DDS -

BOOLEAN FALSE (p. 299).

For large data, counts whole samples, not fragments.

6.23.2.15 DDS LongLong DDS DataWriterProtocolStatus::pulled -

sample bytes

The number of bytes of user samples pulled from local DataWriter by matching

DataReaders.

Pulled samples are samples sent for repairs, for late joiners,

and all samples sent by the local DataWriter when DDS -

DataWriterProtocolQosPolicy::push on write (p. 537) is DDS -

BOOLEAN FALSE (p. 299).

For large data, counts bytes of whole samples, not fragments.

6.23.2.16 DDS LongLong DDS DataWriterProtocolStatus::pulled -

sample bytes change

The incremental change in the number of bytes of user samples pulled from local

DataWriter by matching DataReaders since the last time the status was read.

Pulled samples are samples sent for repairs, for late joiners,

and all samples sent by the local DataWriter when DDS -

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

548 Class Documentation

DataWriterProtocolQosPolicy::push on write (p. 537) is DDS -

BOOLEAN FALSE (p. 299).

For large data, counts bytes of whole samples, not fragments.

6.23.2.17 DDS LongLong DDS -

DataWriterProtocolStatus::received ack count

The number of ACKs from a remote DataReader received by a local DataWriter.

6.23.2.18 DDS LongLong DDS -

DataWriterProtocolStatus::received ack count change

The incremental change in the number of ACKs from a remote DataReader

received by a local DataWriter since the last time the status was read.

6.23.2.19 DDS LongLong DDS -

DataWriterProtocolStatus::received ack bytes

The number of bytes of ACKs from a remote DataReader received by a local

DataWriter.

6.23.2.20 DDS LongLong DDS -

DataWriterProtocolStatus::received ack bytes change

The incremental change in the number of bytes of ACKs from a remote

DataReader received by a local DataWriter since the last time the status was

read.

6.23.2.21 DDS LongLong DDS -

DataWriterProtocolStatus::received nack count

The number of NACKs from a remote DataReader received by a local

DataWriter.

6.23.2.22 DDS LongLong DDS -

DataWriterProtocolStatus::received nack count change

The incremental change in the number of NACKs from a remote DataReader

received by a local DataWriter since the last time the status was read.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.23 DDS DataWriterProtocolStatus Struct Reference 549

6.23.2.23 DDS LongLong DDS -

DataWriterProtocolStatus::received nack bytes

The number of bytes of NACKs from a remote DataReader received by a local

DataWriter.

6.23.2.24 DDS LongLong DDS -

DataWriterProtocolStatus::received nack bytes change

The incremental change in the number of bytes of NACKs from a remote

DataReader received by a local DataWriter since the last time the status was

read.

6.23.2.25 DDS LongLong DDS DataWriterProtocolStatus::sent -

gap count

The number of GAPs sent from local DataWriter to matching remote DataRead-

ers.

6.23.2.26 DDS LongLong DDS DataWriterProtocolStatus::sent -

gap count change

The incremental change in the number of GAPs sent from local DataWriter to

matching remote DataReaders since the last time the status was read.

6.23.2.27 DDS LongLong DDS DataWriterProtocolStatus::sent -

gap bytes

The number of bytes of GAPs sent from local DataWriter to matching remote

DataReaders.

6.23.2.28 DDS LongLong DDS DataWriterProtocolStatus::sent -

gap bytes change

The incremental change in the number of bytes of GAPs sent from local

DataWriter to matching remote DataReaders since the last time the status

was read.

6.23.2.29 DDS LongLong DDS -

DataWriterProtocolStatus::rejected sample count

The number of times a sample is rejected due to exceptions in the send path.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

550 Class Documentation

6.23.2.30 DDS LongLong DDS -

DataWriterProtocolStatus::rejected sample count change

The incremental change in the number of times a sample is rejected due to

exceptions in the send path since the last time the status was read.

6.23.2.31 DDS Long DDS DataWriterProtocolStatus::send -

window size

Current maximum number of outstanding samples allowed in the DataWriter’s

queue.

Spans the range from DDS RtpsReliableWriterProtocol t::mi n send -

window size (p. 901) to DDS RtpsReliableWriterProtocol t::max -

send window size (p. 901).

6.23.2.32 struct DDS SequenceNumber t

DDS DataWriterProtocolStatus::ﬁrst available sample -

sequence number [read]

The sequence number of the ﬁrst available sample currently queued in the local

DataWriter.

Applies only for local DataWriter status.

6.23.2.33 struct DDS SequenceNumber t

DDS DataWriterProtocolStatus::last available sample -

sequence number [read]

The sequence number of the last available sample currently queued in the local

DataWriter.

Applies only for local DataWriter status.

6.23.2.34 struct DDS SequenceNumber t

DDS DataWriterProtocolStatus::ﬁrst -

unacknowledged sample sequence number

[read]

The sequence number of the ﬁrst unacknowledged sample currently queued in

the local DataWriter.

Applies only for local DataWriter status.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.23 DDS DataWriterProtocolStatus Struct Reference 551

6.23.2.35 struct DDS SequenceNumber t

DDS DataWriterProtocolStatus::ﬁrst -

available sample virtual sequence number

[read]

The virtual sequence number of the ﬁrst available sample currently queued in

the local DataWriter.

Applies only for local DataWriter status.

6.23.2.36 struct DDS SequenceNumber t

DDS DataWriterProtocolStatus::last -

available sample virtual sequence number

[read]

The virtual sequence number of the last available sample currently queued in

the local DataWriter.

Applies only for local DataWriter status.

6.23.2.37 struct DDS SequenceNumber t

DDS DataWriterProtocolStatus::ﬁrst -

unacknowledged sample virtual sequence number

[read]

The virtual sequence number of the ﬁrst unacknowledged sample currently

queued in the local DataWriter.

Applies only for local DataWriter status.

6.23.2.38 DDS InstanceHandle t DDS -

DataWriterProtocolStatus::ﬁrst unacknowledged -

sample subscription handle

The handle of a remote DataReader that has not acknowledged the ﬁrst unac-

knowledged sample of the local DataWriter.

Applies only for local DataWriter status.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

552 Class Documentation

6.23.2.39 struct DDS SequenceNumber t

DDS DataWriterProtocolStatus::ﬁrst unelapsed -

keep duration sample sequence number

[read]

The sequence number of the ﬁrst sample whose keep duration has not yet

elapsed.

Applicable only when DDS DataWriterProtocolQosPolicy:: disable -

positive acks (p. 537) is set.

Sequence number of the ﬁrst sample kept in the DataWriter’s queue whose keep -

duration (applied when DDS DataWriterProtocolQosPolicy::disable -

positive acks (p. 537) is set) has not yet elapsed.

Applies only for local DataWriter status.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.24 DDS DataWriterQos Struct Reference 553

6.24 DDS DataWriterQos Struct Reference

QoS policies supported by a DDSDataWriter (p. 1113) entity.

Public Attributes

struct DDS DurabilityQosPolicy durability

Durability policy, DURABILITY ( p. 348).

struct DDS DurabilityServiceQosPolicy durability service

DurabilityService policy, DURABILITY SERVICE ( p. 370).

struct DDS DeadlineQosPolicy deadline

Deadline policy, DEADLINE ( p. 353).

struct DDS LatencyBudgetQosPolicy latency budget

Latency budget policy, LATENCY BUDGET ( p. 354).

struct DDS LivelinessQosPolicy liveliness

Liveliness policy, LIVELINESS ( p. 358).

struct DDS ReliabilityQosPolicy reliability

Reliability policy, RELIABILITY ( p. 362).

struct DDS DestinationOrderQosPolicy destination order

Destination order policy, DESTINATION ORDER ( p. 365).

struct DDS HistoryQosPolicy history

History policy, HISTORY ( p. 367).

struct DDS ResourceLimitsQosPolicy resource limits

Resource limits policy, RESOURCE LIMITS ( p. 371).

struct DDS TransportPriorityQosPolicy transport priority

Transport priority policy, TRANSPORT PRIORITY ( p. 373).

struct DDS LifespanQosPolicy lifespan

Lifespan policy, LIFESPAN ( p. 374).

struct DDS UserDataQosPolicy user data

User data policy, USER DATA ( p. 345).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

554 Class Documentation

struct DDS OwnershipQosPolicy ownership

Ownership policy, OWNERSHIP ( p. 355).

struct DDS OwnershipStrengthQosPolicy ownership strength

Ownership strength policy, OWNERSHIP STRENGTH ( p. 357).

struct DDS WriterDataLifecycleQosPolicy writer data lifecycle

Writer data lifecycle policy, WRITER DATA LIFECYCLE ( p. 375).

struct DDS DataWriterResourceLimitsQosPoli cy writer -

resource limits

<<eXtension>> (p. 199) Writer resource limits policy, DATA -

WRITER RESOURCE LIMITS ( p. 409).

struct DDS DataWriterProto colQosPolicy protocol

<<eXtension>> (p. 199) DDSDataWriter ( p. 1113) protocol policy,

DATA WRITER PROTOCOL ( p. 414)

struct DDS TransportSelecti onQosPolicy transport selection

<<eXtension>> (p. 199) Transport plugin selection policy, TRANS-

PORT SELECTION ( p. 382).

struct DDS TransportUnicastQosPolicy unicast

<<eXtension>> (p. 199) Unicast transport policy, TRANSPORT -

UNICAST ( p. 383).

struct DDS PublishModeQosPolicy publish mode

<<eXtension>> (p. 199) Publish mode policy, PUBLISH MODE

( p. 420).

struct DDS PropertyQosPolicy property

<<eXtension>> (p. 199) Property policy, PROPERTY ( p. 436).

struct DDS BatchQosPolicy batch

<<eXtension>> (p. 199) Batch policy , BATCH ( p. 431).

struct DDS MultiChannelQosPolicy multi channel

<<eXtension>> (p. 199) Multi channel policy, MULTICHANNEL

( p. 435).

struct DDS AvailabilityQosPolicy availability

<<eXtension>> (p. 199) Availability policy, AVAILABILITY ( p. 442).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.24 DDS DataWriterQos Struct Reference 555

struct DDS EntityNameQosPolicy publication name

<<eXtension>> (p. 199) EntityName policy, ENTITY NAME ( p. 445).

struct DDS TypeSupportQosPolicy type support

<<eXtension>> (p. 199) Type support data, TYPESUPPORT ( p. 429).

6.24.1 Detailed Description

QoS policies supported by a DDSDataWriter (p. 1113) entity.

You must set certain members in a consistent manner:

- DDS DataWriterQos::history.depth <= DDS DataWriterQos::resource -

limits.max samples per instance

- DDS DataWriterQos::resource limits.max samples per instance <= DDS -

DataWriterQos::resource limits.max samples

- DDS DataWriterQos::resource limits.initial samples <= DDS -

DataWriterQos::resource limits.max samples

- DDS DataWriterQos::resource limits.initial instances <= DDS -

DataWriterQos::resource limits.max instances

- length of DDS DataWriterQos::user data.value <= DDS -

DomainParticipantQos::resource limits (p. 591) .writer user data -

max length

If any of the above are not true, DDSDataWriter::set qos (p. 1126)

and DDSDataWriter::set qos with proﬁle (p. 1127) and DDSPub-

lisher::set default datawriter qos (p. 1351) and DDSPublisher::set -

default datawriter qos with proﬁle (p. 1351) will fail with DDS -

RETCODE INCONSISTENT POLICY (p. 315) and DDSPub-

lisher::create datawriter (p. 1355) and DDSPublisher::create -

datawriter with proﬁle (p. 1357) and will return NULL.

Entity:

DDSDataWriter (p. 1113)

See also:

QoS Policies (p. 331) allowed ranges within each Qos.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

556 Class Documentation

6.24.2 Member Data Documentation

6.24.2.1 struct DDS DurabilityQosPolicy

DDS DataWriterQos::durability [read]

Durability policy, DURABILITY (p. 348).

6.24.2.2 struct DDS DurabilityServiceQosPolicy

DDS DataWriterQos::durability service [read]

DurabilityService policy, DURABILITY SERVICE (p. 370).

6.24.2.3 struct DDS DeadlineQosPolicy DDS -

DataWriterQos::deadline [read]

Deadline policy, DEADLINE (p. 353).

6.24.2.4 struct DDS LatencyBudgetQosPol icy

DDS DataWriterQos::latency budget [read]

Latency budget policy, LATENCY BUDGET (p. 354).

6.24.2.5 struct DDS LivelinessQosPolicy

DDS DataWriterQos::liveliness [read]

Liveliness policy, LIVELINESS (p. 358).

6.24.2.6 struct DDS ReliabilityQosPolicy

DDS DataWriterQos::reliabil ity [read]

Reliability policy, RELIABILITY (p. 362).

6.24.2.7 struct DDS DestinationOrderQosPolicy

DDS DataWriterQos::destination order [read]

Destination order policy, DESTINATION ORDER (p. 365).

6.24.2.8 struct DDS HistoryQosPolicy DDS -

DataWriterQos::history [read]

History policy, HISTORY (p. 367).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.24 DDS DataWriterQos Struct Reference 557

6.24.2.9 struct DDS ResourceLimitsQosPolicy

DDS DataWriterQos::resource li mi ts [read]

Resource limits policy, RESOURCE LIMITS (p. 371).

6.24.2.10 struct DDS Transp ortPriorityQosPolicy

DDS DataWriterQos::transport priority [read]

Transport priority policy, TRANSPORT PRIORITY (p. 373).

6.24.2.11 struct DDS LifespanQosPolicy

DDS DataWriterQos::lif espan [read]

Lifespan policy, LIFESPAN (p. 374).

6.24.2.12 struct DDS UserDataQosPolicy

DDS DataWriterQos::user data [read]

User data policy, USER DATA (p. 345).

6.24.2.13 struct DDS OwnershipQosPolicy

DDS DataWriterQos::ownership [read]

Ownership policy, OWNERSHIP (p. 355).

6.24.2.14 struct DDS OwnershipStrengthQosPolicy

DDS DataWriterQos::ownership strength [read]

Ownership s trength policy, OWNERSHIP STRENGTH (p. 357).

6.24.2.15 struct DDS WriterDataLifecycleQosPolicy

DDS DataWriterQos::writer data lifecycle [read]

Writer data lifecycle policy, WRITER DATA LIFECYCLE (p. 375).

6.24.2.16 struct DDS DataWriterResourceLimitsQosPolicy

DDS DataWriterQos::writer resource li mi ts [read]

<<eXtension>> ( p. 199 ) Writer resource limits policy, DATA WRITER -

RESOURCE LIMITS (p. 409).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

558 Class Documentation

6.24.2.17 struct DDS DataWriterProtocolQosPolicy

DDS DataWriterQos::protocol [read]

<<eXtension>> ( p. 199) DDSDataWriter (p. 1113) protocol policy,

DATA WRITER PROTOCOL (p. 414)

6.24.2.18 struct DDS TransportSelectionQosPolicy

DDS DataWriterQos::transport selection [read]

<<eXtension>> ( p. 199) Transport plugin selection policy, TRANS-

PORT SELECTION (p. 382).

Speciﬁes the transports available for use by the DDSDataWriter (p. 1113).

6.24.2.19 struct DDS TransportUnicastQosPol icy

DDS DataWriterQos::unicast [read]

<<eXtension>> ( p. 199 ) Unicast transport policy, TRANSPORT -

UNICAST (p. 383).

Speciﬁes the unicast transport interfaces and ports on which messages can be

received.

The unicast interfaces are used to receive mess ages from DDSDataReader

(p. 1087) entities in the domain.

6.24.2.20 struct DDS PublishModeQosPolicy

DDS DataWriterQos::publish mode [read]

<<eXtension>> ( p. 199) Publish mode policy, PUBLISH MODE (p. 420).

Determines whether the DDSDataWriter (p. 1113) publishes data syn-

chronously or asynchronously and how.

6.24.2.21 struct DDS PropertyQosPolicy

DDS DataWriterQos::property [read]

<<eXtension>> ( p. 199) Property policy, PROPERTY (p. 436).

6.24.2.22 struct DDS BatchQosPolicy DDS DataWriterQos::batch

[read]

<<eXtension>> ( p. 199) Batch policy, BATCH (p. 431).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.24 DDS DataWriterQos Struct Reference 559

6.24.2.23 struct DDS MultiChannelQosPolicy

DDS DataWriterQos::multi channel [read]

<<eXtension>> ( p. 199) Multi channel policy, MULTICHANNEL

(p. 435).

6.24.2.24 struct DDS AvailabilityQosPolicy

DDS DataWriterQos::availability [read]

<<eXtension>> ( p. 199) Availability policy, AVAILABILITY (p. 442).

6.24.2.25 struct DDS EntityNameQosPolicy

DDS DataWriterQos::publication name [read]

<<eXtension>> ( p. 199) EntityName policy, ENTITY NAME (p. 445).

6.24.2.26 struct DDS TypeSupportQosPolicy

DDS DataWriterQos::type supp ort [read]

<<eXtension>> ( p. 199) Type support data, TYPESUPPORT (p. 429).

Optional value that is passed to a type plugin’s on endpoint attached and seri-

alization functions.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

560 Class Documentation

6.25 DDS DataWriterResourceLimitsQosPolicy

Struct Reference

Various settings that conﬁgure how a DDSDataWriter (p. 1113) allocates and

uses physical memory for internal resources.

Public Attributes

DDS Long initial concurrent blocking threads

The initial number of threads that are allowed to concurrently block on write

call on the same DDSDataWriter ( p. 1113).

DDS Long max concurrent blocking threads

The maximum number of threads that are allowed to concurrently block on

write call on the same DDSDataWriter ( p. 1113).

DDS Long max remote reader ﬁlters

The maximum number of remote DataReaders for which the DDS-

DataWriter ( p. 1113) will perform content-based ﬁltering.

DDS Long initial batches

Represents the initial number of batches a DDSDataWriter ( p. 1113) will

manage.

DDS Long max batches

Represents the maximum number of batches a DDSDataWriter ( p. 1113)

will manage.

DDS DataWriterResourceLimitsInstanceReplacementKind

instance replacement

Sets the kinds of instances allowed to be replaced when instance resource

limits are reached.

DDS Boolean replace empty instances

Whether or not to replace empty instances during instance replacement.

DDS Boolean autoregister instances

Whether or not to automatically register new instances.

DDS Long initial virtual writers

The initial number of virtual writers supported by a DDSDataWriter

( p. 1113).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.25 DDS DataWriterResourceLimitsQosPolicy Struct Reference 561

DDS Long max virtual writers

The maximum number of virtual writers supported by a DDSDataWriter

( p. 1113).

DDS Long max remote readers

The maximum number of remote readers supported by a DDSDataWriter

( p. 1113).

DDS Long max app ack remote readers

The maximum number of application-level acknowledging remote readers sup-

ported by a DDSDataWriter ( p. 1113).

6.25.1 Detailed Description

Various settings that conﬁgure how a DDSDataWriter (p. 1113) allocates and

uses physical memory for internal resources.

DataWriters must allocate internal structures to handle the simultaneously

blocking of threads trying to call FooDataWriter::write (p.

1484) on the same

DDSDataWriter (p. 1113), for the storage used to batch small samples, and

for content-based ﬁlters speciﬁed by DataReaders.

Most of these internal structures start at an initial size and, by default, will

be grown as needed by dynamically allocating additional me mory. You may

set ﬁxed, maximum sizes for these internal structures if you want to bound

the amount of memory that can be used by a DDSDataWriter (p. 1113). By

setting the initial size to the maximum size, you will prevent RTI Connext from

dynamically allocating any memory after the creation of the DDSDataWriter

(p. 1113).

This QoS policy is an extension to the DDS standard.

Entity:

DDSDataWriter (p. 1113)

Properties:

RxO (p. 340) = N/A

Changeable (p. 340) = NO (p. 340)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

562 Class Documentation

6.25.2 Member Data Documentation

6.25.2.1 DDS Long DDS -

DataWriterResourceLimitsQosPolicy::initial concurrent -

blocking threads

The initial number of threads that are allowed to concurrently block on write

call on the same DDSDataWriter (p. 1113).

This value only applies if DDS HistoryQosPolicy (p. 758) has its

kind set to DDS KEEP ALL HISTORY QOS (p. 368) and DDS -

ReliabilityQosPolicy::max blocki ng time (p. 868) is > 0.

[default] 1

[range] [1, 10000], <= max concurrent blocking threads

6.25.2.2 DDS Long DDS -

DataWriterResourceLimitsQosPolicy::max -

concurrent blocking threads

The maximum number of threads that are allowed to concurrently block on

write call on the same DDSDataWriter (p. 1113).

This value only applies if DDS HistoryQosPolicy (p. 758) has its

kind set to DDS KEEP ALL HISTORY QOS (p. 368) and DDS -

ReliabilityQosPolicy::max blocki ng time (p. 868) is > 0.

[default] DDS LENGTH UNLIMITED (p. 371)

[range] [1, 10000] or DDS LENGTH UNLIMITED (p. 371), >= initial -

concurrent blocking threads

6.25.2.3 DDS Long DDS -

DataWriterResourceLimitsQosPolicy::max -

remote reader ﬁlters

The maximum number of remote DataReaders for which the DDSDataWriter

(p. 1113) will perform content-based ﬁltering.

[default] 32

[range] [0, (2

∧

31)-2] or DDS LENGTH UNLIMITED (p. 371).

0: The DDSDataWriter (p. 1113) will not perform ﬁltering for any DDS-

DataReader (p. 1087).

1 to (2

∧

31)-2: The DataWriter will ﬁlter for up to the speciﬁed number of

DataReaders. In addition, the Datawriter will store the result of the ﬁltering

per sample per DataReader.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.25 DDS DataWriterResourceLimitsQosPolicy Struct Reference 563

DDS LENGTH UNLIMITED (p. 371): The DataWriter will ﬁlter for up to

∧

31)-2 DataReaders. However, in this case, the DataWriter will not store the

ﬁltering result per sample per DataReader. Thus, if a sample is resent (such as

due to a loss of reliable communication), the sample will be ﬁltered again.

6.25.2.4 DDS Long DDS -

DataWriterResourceLimitsQosPolicy::initial batches

Represents the initial number of batches a DDSDataWriter (p. 1113) will

manage.

[default] 8

[range] [1,100 million]

See also:

DDS BatchQosPolicy (p. 476)

6.25.2.5 DDS Long DDS -

DataWriterResourceLimitsQosPolicy::max batches

Represents the maximum number of batches a DDSDataWriter (p. 1113) will

manage.

[default] DDS LENGTH UNLIMITED (p. 371)

When batching is enabled, the maximum number of samples that a DDS-

DataWriter (p. 1113) can store is limited by this value and DDS -

ResourceLimitsQosPolicy::max samples (p. 881).

[range] [1,100 million] or DDS LENGTH UNLIMITED (p. 371) >=

DDS RtpsReliableWriterProtocol t::heartbeats per max samples

(p. 896) if batching is enabled

See also:

DDS BatchQosPolicy (p. 476)

6.25.2.6 DDS -

DataWriterResourceLimitsInstanceReplacementKind

DDS DataWriterResourceLimitsQosPolicy::instance -

replacement

Sets the kinds of instances allowed to be replaced when instance re source limits

are reached.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

564 Class Documentation

When a DDSDataWriter (p. 1113)’s number of active instances is greater

than DDS ResourceLimitsQosPolicy::max instances (p. 882), it will try

to make room by replacing an existing instance. This ﬁeld speciﬁes the kinds

of instances allowed to be replaced.

If a replaceable instance is not available, either an out-of-resources exception

will be returned, or the writer may block if the instance reclamation was done

when writing.

[default] DDS UNREGISTERED INSTANCE REPLACEMENT

(p. 411)

See also:

DDS DataWriterResourceLimitsInstanceReplacementKind

(p. 410)

6.25.2.7 DDS Boolean DDS -

DataWriterResourceLimitsQosPolicy::replace empty -

instances

Whether or not to replace empty instances during instance replacement.

When a DDSDataWriter (p. 1113) has more active instances than allowed

by DDS ResourceLimitsQosPolicy::max instances (p. 882), it tries to

make room by replacing an existing instance. This ﬁeld conﬁgures whether

empty instances (i.e. instances with no samples) may be replaced. If

set DDS BOOLEAN TRUE (p. 298), then a DDSDataWriter (p. 1113)

will ﬁrst try reclaiming empty instances, before trying to replace whatever

is speciﬁed by DDS DataWriterResourceLimitsQosPolicy::instance -

replacement (p. 563).

[default] DDS BOOLEAN FALSE (p. 299)

See also:

DDS DataWriterResourceLimitsInstanceReplacementKind

(p. 410)

6.25.2.8 DDS Boolean DDS -

DataWriterResourceLimitsQosPolicy::autoregister -

instances

Whether or not to automatically register new instances.

[default] DDS BOOLEAN TRUE (p. 298)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.25 DDS DataWriterResourceLimitsQosPolicy Struct Reference 565

When set to true, it is possible to write with a non-NIL handle of an instance

that is not registe red: the write operation will succeed and the instance will be

registered. Otherwise, that write operation would fail.

See also:

FooDataWriter::write (p. 1484)

6.25.2.9 DDS Long DDS -

DataWriterResourceLimitsQosPolicy::initial virtual -

writers

The initial number of virtual writers supported by a DDSDataWriter

(p. 1113).

[default] 1

[range] [1, 1000000], or DDS LENGTH UNLIMITED (p. 371)

6.25.2.10 DDS Long DDS -

DataWriterResourceLimitsQosPolicy::max virtual -

writers

The maximum number of virtual writers supported by a DDSDataWriter

(p. 1113).

Sets the maximum number of unique virtual writers supported by a DDS-

DataWriter (p. 1113), where virtual writers are added when samples are writ-

ten with the virtual writer GUID.

This ﬁeld is specially relevant in the conﬁguration of Persistence Service

DataWriters since these DataWriters will publish samples on behalf of multiple

virtual writers.

[default] DDS LENGTH UNLIMITED (p. 371)

[range] [1, 1000000], or DDS LENGTH UNLIMITED (p. 371)

6.25.2.11 DDS Long DDS -

DataWriterResourceLimitsQosPolicy::max remote -

readers

The maximum number of remote readers supported by a DDSDataWriter

(p. 1113).

[default] DDS LENGTH UNLIMITED (p. 371)

[range] [1, 1000000], or DDS LENGTH UNLIMITED (p. 371)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

566 Class Documentation

6.25.2.12 DDS Long DDS -

DataWriterResourceLimitsQosPolicy::max app ack -

remote readers

The maximum number of application-level acknowledging remote readers sup-

ported by a DDSDataWriter (p. 1113).

[default] DDS LENGTH UNLIMITED (p. 371)

[range] [1, 1000000], or DDS LENGTH UNLIMITED (p. 371)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.26 DDS DeadlineQosPol icy Struct Reference 567

6.26 DDS DeadlineQosPolicy Struct Reference

Expresses the maximum duration (deadline) within which an instance is ex-

pected to be updated.

Public Attributes

struct DDS Duration t period

Duration of the deadline period.

6.26.1 Detailed Description

Expresses the maximum duration (deadline) within which an instance is ex-

pected to be updated.

A DDSDataReader (p. 1087) expects a new sample updating the value of each

instance at least once every period. That is, period speciﬁes the maximum

expected elapsed time between arriving data samples.

A DDSDataWriter (p. 1113) indicates that the application commits to write

a new value (using the DDSDataWriter (p. 1113)) for each instance managed

by the DDSDataWriter (p. 1113) at least once every period.

This QoS can be used during system integration to ensure that applications

have been coded to meet design speciﬁcations.

It can also be used during run time to detect when systems are performing

outside of design speciﬁcations. Receiving applications can take appropriate

actions to prevent total system failure when data is not received in time. For

topics on which data is not expected to be periodic, period should be set to an

inﬁnite value.

Entity:

DDSTopic (p. 1419), DDSDataReader (p. 1087), DDSDataWriter

(p. 1113)

Status:

DDS OFFERED DEADLINE MISSED STATUS (p. 323), DDS -

REQUESTED DEADLINE MISSED STATUS (p. 323), DDS -

OFFERED INCOMPATIBLE QOS STATUS (p. 323), DDS -

REQUESTED INCOMPATIBLE QOS STATUS (p. 323)

Properties:

RxO (p. 340) = YES

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

568 Class Documentation

Changeable (p. 340) = YES (p. 340)

6.26.2 Usage

This policy is useful for cases where a DDSTopic (p. 1419) is expected to

have each instance updated periodically. On the publishing side this setting

establishes a contract that the application must meet. On the subscribing side

the setting establishes a minimum requirement for the remote publishers that

are expected to supply the data values.

When RTI Connext ’matches’ a DDSDataWriter (p. 1113) and a DDS-

DataReader (p. 1087) it checks whether the settings are compatible (i.e., of-

fered deadline <= requested deadline); if they are not, the two entities are

informed (via the DDSListener (p. 1318) or DDSCondition (p. 1075) mech-

anism) of the incompatibility of the QoS settings and communication will not

occur.

Assuming that the reader and writer ends have compatible settings, the ful-

ﬁlment of this contract is monitored by RTI Connext and the application is

informed of any violations by means of the proper DDSListener (p. 1318) or

DDSCondition (p. 1075).

6.26.3 Compatibility

The value oﬀered is considered compatible with the value requested if and only

if the inequality oﬀered period <= requested period holds.

6.26.4 Consistency

The setting of the DEADLINE (p. 353) policy must be set consistently with

that of the TIME BASED FILTER (p. 360).

For these two policies to be consistent the settings must be such that deadline

period >= minimum separation.

An attempt to set these policies in an inconsistent manner will result in DDS -

RETCODE INCONSISTENT POLICY (p. 315) in set qos (abstract)

(p. 1254), or the DDSEntity (p. 1253) will not be created.

For a DDSDataReader (p. 1087), the DEADLINE (p. 353) policy and

DDS TimeBasedFilterQosPolicy (p. 954) may interact such that even

though the DDSDataWriter (p.

1113) is writing samples fast enough to ful-

ﬁll its commitment to its own deadline, the DDSDataReader (p. 1087) may

see violations of its deadline. This happens because RTI Connext will drop any

samples received within the DDS TimeBasedFilterQosPolicy::minimum -

separation (p. 957). To avoid triggering the DDSDataReader (p. 1087)’s

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.26 DDS DeadlineQosPol icy Struct Reference 569

deadline, even though the matched DDSDataWriter (p. 1113) is meeting its

own deadline, set the two QoS parameters so that:

reader deadline >= reader minimum separation + writer deadline

See DDS TimeBasedFilterQosPolicy (p. 954) for more information about

the interactions between deadlines and time-based ﬁlters.

See also:

DDS TimeBasedFilterQosPolicy (p. 954)

6.26.5 Member Data Documentation

6.26.5.1 struct DDS Duration t DDS DeadlineQosPolicy::period

[read]

Duration of the deadline period.

[default] DDS DURATION INFINITE (p. 305)

[range] [1 nanosec, 1 ye ar] or DDS DURATION INFINITE (p. 305), >=

DDS TimeBasedFilterQosPolicy::mi nimum separation (p. 957)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

570 Class Documentation

6.27 DDS DestinationOrderQosPolicy Struct

Reference

Controls how the middleware will deal with data sent by multiple DDS-

DataWriter (p. 1113) entities for the same instance of data (i.e., same

DDSTopic (p. 1419) and key).

Public Attributes

DDS DestinationOrderQosPolicyKind kind

Speciﬁes the desired kind of destination order.

struct DDS Duration t source timestamp tol erance

<<eXtension>> (p. 199) Allowed tolerance between source timestamps of

consecutive samples.

6.27.1 Detailed Description

Controls how the middleware will deal with data sent by multiple DDS-

DataWriter (p. 1113) entities for the same instance of data (i.e., same

DDSTopic (p. 1419) and key).

Entity:

DDSTopic (p. 1419), DDSDataReader (p. 1087), DDSDataWriter

(p. 1113)

Status:

DDS OFFERED INCOMPATIBLE QOS STATUS (p. 323),

DDS REQUESTED INCOMPATIBLE QOS STATUS (p. 323)

Properties:

RxO (p. 340) = YES

Changeable (p. 340) = UNTIL ENABLE (p. 340)

6.27.2 Usage

When multiple DataWriters send data for the same topic, the order in which

data from diﬀerent DataWriters are received by the applications of diﬀerent

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.27 DDS DestinationOrderQosPolicy Struct Reference 571

DataReaders may be diﬀerent. So diﬀerent DataReaders may not receive the

same ”last” value when DataWriters stop sending data.

This QoS policy controls how each subscriber resolves the ﬁnal value of a data

instance that is written by multiple DDSDataWriter (p. 1113) entities (which

may be associated with diﬀerent DDSPublisher (p. 1346) entities) running on

diﬀerent nodes.

The default setting, DDS BY RECEPTION TIMESTAMP -

DESTINATIONORDER QOS (p. 366), indicates that (assuming the

OWNERSHIP STRENGTH (p. 357) policy allows it) the latest received

value for the instance should be the one whose value is kept. That is, data

will be delivered by a DDSDataReader (p. 1087) in the order in which it was

received (which may lead to inconsistent ﬁnal values).

The setting DDS BY SOURCE TIMESTAMP -

DESTINATIONORDER QOS (p. 366) indicates that (assuming the

OWNERSHIP STRENGTH (p. 357) allows it, within each instance) the

source timestamp of the change shall be used to determine the most recent

information. That is, data will be delivered by a DDSDataReader (p. 1087)

in the order in which it was sent. If data arrives on the network with a source

timestamp that is later than the source timestamp of the last data delivered,

the new data will b e dropped. This ’by source timestamp’ ordering therefore

works best when system clocks are relatively synchronized among writing

machines.

When using DDS BY SOURCE TIMESTAMP -

DESTINATIONORDER QOS (p. 366), not all data sent by multiple

DDSDataWriter (p. 1113) entities may be delivered to a DDSDataReader

(p. 1087) and not all DataReaders will see the same data sent by DataWriters.

However, all DataReaders will see the same ”ﬁnal” data when DataWriters

”stop” sending data. This is the only setting that, in the case of concurrently

publishing DDSDataWriter (p. 1113) entities updating the same instance of

a shared-ownership topic, ensures all subscribers will end up with the same

ﬁnal value for the instance.

This QoS can be used to create systems that have the property of ”eventual

consistency.” Thus intermediate states across multiple applications may be in-

consistent, but when DataWriters stop sending changes to the same topic, all

applications will end up having the same state.

6.27.3 Compatibility

The value oﬀered is considered compatible with the value requested

if and only if the inequality oﬀered kind >= requested kind eval-

uates to ’TRUE’. For the purposes of this inequality, the values

of DDS DestinationOrderQosPolicy::kind (p. 572) are consid-

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

572 Class Documentation

ered ordered such that DDS BY RECEPTION TIMESTAMP -

DESTINATIONORDER QOS (p. 366) < DDS BY SOURCE -

TIMESTAMP DESTINATIONORDER QOS (p. 366)

6.27.4 Member Data Documentation

6.27.4.1 DDS DestinationOrderQosPolicyKind

DDS DestinationOrderQosPolicy::kind

Speciﬁes the desired kind of destination order.

[default] DDS BY RECEPTION TIMESTAMP -

DESTINATIONORDER QOS (p. 366),

6.27.4.2 struct DDS Duration t DDS -

DestinationOrderQosPolicy::source timestamp tolerance

[read]

<<eXtension>> ( p. 199) Allowed tolerance between source timestamps of

consecutive samples.

When a DDSDataWriter (p. 1113) sets DDS -

DestinationOrderQosPolicyKind (p. 366) to DDS BY SOURCE -

TIMESTAMP DESTINATIONORDER QOS (p. 366), when when

writing a sample, its timestamp must not be less than the timestamp of the

previously written sample. However, if it is less than the timestamp of the

previously written sample but the diﬀerence is less than this tolerance, the

sample will use the previously written sample’s timestamp as its timestamp.

Otherwise, if the diﬀerence is greater than this tolerance, the write will fail.

When a DDSDataReader (p. 1087) sets DDS -

DestinationOrderQosPolicyKind (p. 366) to DDS BY SOURCE -

TIMESTAMP DESTINATIONORDER QOS (p. 366), the DDS-

DataReader (p. 1087) will accept a sample only if the diﬀerence between

its source timestamp and the reception timestamp is no greater than this

tolerance. Otherwise, the sample is rejected.

[default] 100 m illiseconds for DDSDataWriter (p. 1113), 30 seconds for

DDSDataReader (p. 1087)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.28 DDS DiscoveryConﬁgQosPolicy Struct Reference 573

6.28 DDS Discove ryConﬁgQosPolicy Struct

Reference

Settings for discovery conﬁguration.

Public Attributes

struct DDS Duration t participant liveliness lease duration

The liveliness lease duration for the participant.

struct DDS Duration t participant liveliness assert period

The period to assert liveliness for the participant.

DDS RemoteParticipantPurgeKind remote participant purge -

kind

The participant’s behavior for maintaining knowledge of remote participants

(and their contained entities) with which discovery communication has been

lost.

struct DDS Duration t max liveliness loss detecti on period

The maximum amount of time between when a remote entity stops maintain-

ing its liveliness and when the matched local entity realizes that fact.

DDS Long initial participant announcements

The number of initial announcements sent when a participant is ﬁrst enabl ed

or when a remote participant is newly discovered.

struct DDS Duration t min initial participant announcement -

period

The minimum period between initial announcements when a participant is

ﬁrst enabled or when a remote participant is newly discovered.

struct DDS Duration t max initial participant announcement -

period

The maximum period between initial announcements when a participant is

ﬁrst enabled or when a remote participant is newly discovered.

struct DDS BuiltinTopicReaderResourceLimits t participant -

reader resource limits

Resource limits.

struct DDS RtpsReliableReaderProtocol t publication reader

RTPS protocol-related conﬁguration settings for a built-in publication reader.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

574 Class Documentation

struct DDS BuiltinTopicReaderResourceLimits t publication -

reader resource limits

Resource limits.

struct DDS RtpsReliableReaderProtocol t subscription reader

RTPS protocol-related conﬁguration settings for a built-in subscription

reader.

struct DDS BuiltinTopicReaderResourceLimits t subscription -

reader resource limits

Resource limits.

struct DDS RtpsReliableWriterProtocol t publication writer

RTPS protocol-related conﬁguration settings for a built-in publication writer.

struct DDS WriterDataLifecycleQosPolicy publication writer -

data lifecycle

Writer data lifecycle settings for a built-in publication writer.

struct DDS RtpsReliableWriterProtocol t subscription writer

RTPS protocol-related conﬁguration settings for a built-in subscription

writer.

struct DDS WriterDataLifecycleQosPolicy subscription writer -

data lifecycle

Writer data lifecycle settings for a built-in subscription writer.

DDS DiscoveryConﬁgBuiltinPluginKindMask builtin -

discovery plugins

The kind mask for built-in discovery plugins.

struct DDS RtpsReliableReaderProtocol t participant message -

reader

RTPS protocol-related conﬁguration settings for a built-in participant mes-

sage reader.

struct DDS RtpsReliableWriterProtocol t participant message -

writer

RTPS protocol-related conﬁguration settings for a built-in participant mes-

sage writer.

struct DDS PublishModeQosPolicy publication writer publish -

mode

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.28 DDS DiscoveryConﬁgQosPolicy Struct Reference 575

<<eXtension>> (p. 199) Publish mode policy, PUBLISH MODE

( p. 420).

struct DDS AsynchronousPublisherQosPolicy asynchronous -

publisher

<<eXtension>> (p. 199) Asynchronous publishing setting s for the Discov-

ery DDSPublisher ( p. 1346) and all entities that are created by it.

6.28.1 Detailed Description

Settings for discovery conﬁguration.

This QoS policy is an extension to the DDS standard.

This QoS policy controls the amount of delay in discovering entities in the

system and the amount of discovery traﬃc in the network.

The amount of network traﬃc required by the discovery process can vary widely,

based on how your application has chosen to conﬁgure the middleware’s network

addressing (e.g., unicast vs. multicast, multicast TTL, etc.), the size of the

system, whether all applications are started at the same time or whether start

times are staggered, and other factors. Your application can use this policy

to make tradeoﬀs between discovery completion time and network bandwidth

utilization. In addition, you can introduce random back-oﬀ periods into the

discovery process to decrease the probability of network contention when many

applications start simultaneously.

Entity:

DDSDomainParticipant (p. 1139)

Properties:

RxO (p. 340) = N/A

Changeable (p. 340) = NO (p. 340)

6.28.2 Member Data Documentation

6.28.2.1 struct DDS Duration t DDS -

DiscoveryConﬁgQosPolicy::participant liveliness lease -

duration [read]

The liveliness lease duration for the participant.

This is the same as the expiration time of the DomainParticipant as deﬁned in

the RTPS protocol.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

576 Class Documentation

If the participant has not refreshed its own liveliness to other participants at

least once within this period, it may be considered as stale by other participants

in the network.

Should be strictly greater than DDS DiscoveryConﬁgQosPolicy::participant -

liveliness assert period (p. 576).

[default] 100 seconds

[range] [1 nanosec,1 year], > participant liveliness assert period

6.28.2.2 struct DDS Duration t DDS -

DiscoveryConﬁgQosPolicy::participant liveliness assert -

period [read]

The period to assert liveliness for the participant.

The period at which the participant will refresh its liveliness to all the peers.

Should be strictly less than DDS DiscoveryConﬁgQosPolicy::participant -

liveliness lease duration (p. 575).

[default] 30 seconds

[range] [1 nanosec,1 year), < participant liveliness lease duration

6.28.2.3 DDS RemoteParticipantPurgeKind DDS -

DiscoveryConﬁgQosPolicy::remote participant purge kind

The participant’s behavior for maintaining knowledge of remote participants

(and their contained entities) with which discovery communication has been

lost.

Most users will not need to change this value from its default, DDS -

LIVELINESS BASED REMOTE PARTICIPANT PURGE (p. 426).

However, DDS NO REMOTE PARTICIPANT PURGE (p. 426) may be

a good choice if the following conditions apply:

1. Discovery communication with a remote participant may be lost while

data communication remains intact. Such will not typically be the case if

discovery takes place over the Simple Discovery Protocol, but may be the

case if the RTI Enterprise Discovery Service is used.

2. Extensive and prolonged lack of discovery communication between partic-

ipants is not expected to be common, either because participant loss itself

is expected to be rare, or because participants may be lost sporadically

but will typically return again.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.28 DDS DiscoveryConﬁgQosPolicy Struct Reference 577

3. Maintaining inter-participant liveliness is problematic, perhaps be-

cause a participant has no writers with the appropriate DDS -

LivelinessQosPolicyKind (p. 358).

[default] DDS LIVELINESS BASED REMOTE PARTICIPANT -

PURGE (p. 426)

6.28.2.4 struct DDS Duration t DDS -

DiscoveryConﬁgQosPolicy::max liveliness loss detection -

period [read]

The maximum amount of time between when a remote entity stops maintaining

its liveliness and when the matched local entity realizes that fact.

Notiﬁcation of the loss of liveliness of a remote entity may come more quickly

that this duration, depending on the liveliness contract between the local and

remote entities and the capabilities of the discovery m echanism in use. For

example, a DDSDataReader (p. 1087) will learn of the loss of liveliness of a

matched DDSDataWriter (p. 1113) within the reader’s oﬀered liveliness lease

duration.

Shortening this duration will increase the responsiveness of entities to communi-

cation failures. However, it will also increase the CPU usage of the application,

as the liveliness of remote entities will be examined more frequently.

[default] 60 seconds

[range] [0, 1 year]

6.28.2.5 DDS Long DDS DiscoveryConﬁgQosPolicy::initial -

participant announcements

The number of initial announcements sent when a participant is ﬁrst enabled

or when a remote participant is newly discovered.

Also, when a new remote participant appears, the local participant can announce

itself to the peers multiple times controlled by this parameter.

[default] 5

[range] [0,1 million]

6.28.2.6 struct DDS Duration t DDS -

DiscoveryConﬁgQosPolicy::min initial participant -

announcement period [read]

The minimum period between initial announcements when a participant is ﬁrst

enabled or when a remote participant is newly discovered.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

578 Class Documentation

A random delay between this and DDS DiscoveryConﬁgQosPolicy::max -

initial participant announcement period (p. 578) is introduced in between

initial announcements when a new remote participant is discovered.

The setting of DDS DiscoveryConﬁgQosPolicy::min initial -

participant announcement period (p. 577) must be consis tent with DDS -

DiscoveryConﬁgQosPolicy::max initial participant announcement -

period (p. 578). For these two values to be consistent, they must verify

that:

DDS DiscoveryConﬁgQosPolicy::min initial -

participant announcement period (p. 577) <= DDS -

DiscoveryConﬁgQosPolicy::max initial participant announcement -

period (p. 578).

[default] 1 second

[range] [1 nanosec,1 year]

6.28.2.7 struct DDS Duration t DDS -

DiscoveryConﬁgQosPolicy::max initial participant -

announcement period [read]

The maximum p eriod between initial announcements when a participant is ﬁrst

enabled or when a remote participant is newly discovered.

A random delay between DDS DiscoveryConﬁgQosPolicy::min ini tial -

participant announcement period (p. 577) and this is introduced in be-

tween initial announcements when a new remote participant is discovered.

The setting of DDS DiscoveryConﬁgQosPolicy::max ini tial -

participant announcement period (p. 578) must be consis tent with DDS -

DiscoveryConﬁgQosPolicy::min initial participant announcement -

period (p. 577). For these two values to be consistent, they must verify

that:

DDS DiscoveryConﬁgQosPolicy::min initial -

participant announcement period (p. 577) <= DDS -

DiscoveryConﬁgQosPolicy::max initial participant announcement -

period (p. 578).

[default] 1 second

[range] [1 nanosec,1 year]

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.28 DDS DiscoveryConﬁgQosPolicy Struct Reference 579

6.28.2.8 struct DDS BuiltinTopicReaderResourceLimits t

DDS DiscoveryConﬁgQosPolicy::participant reader -

resource limits [read]

Resource limits.

Resource limit of the built-in topic participant reader. For details, see DDS -

BuiltinTopicReaderResourceLimits t (p. 482).

6.28.2.9 struct DDS RtpsReli ableReaderProtocol t

DDS DiscoveryConﬁgQosPolicy::publication reader

[read]

RTPS protocol-related conﬁguration settings for a built-in publication reader.

For details, refer to the DDS DataReaderQos (p. 515)

6.28.2.10 struct DDS BuiltinTopicReaderResourceLimits t

DDS DiscoveryConﬁgQosPolicy::publication reader -

resource limits [read]

Resource limits.

Resource limit of the built-in topic publication reader. For details, see DDS -

BuiltinTopicReaderResourceLimits t (p. 482).

6.28.2.11 struct DDS RtpsReliableReaderProto col t

DDS DiscoveryConﬁgQosPolicy::subscription reader

[read]

RTPS protocol-related conﬁguration settings for a built-in subscription reader.

For details, refer to the DDS DataReaderQos (p. 515)

6.28.2.12 struct DDS BuiltinTopicReaderResourceLimits t

DDS DiscoveryConﬁgQosPolicy::subscription reader -

resource limits [read]

Resource limits.

Resource limit of the built-in topic s ubscription reader. For details, see DDS -

BuiltinTopicReaderResourceLimits t (p. 482).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

580 Class Documentation

6.28.2.13 struct DDS RtpsReliableWriterProtocol t

DDS DiscoveryConﬁgQosPolicy::publication writer

[read]

RTPS protocol-related conﬁguration settings for a built-in publication writer.

For details, refer to the DDS DataWriterQos (p. 553)

6.28.2.14 struct DDS WriterDataLifecycleQosPolicy

DDS DiscoveryConﬁgQosPolicy::publication writer -

data lifecycle [read]

Writer data lifecycle settings for a built-in publication writer.

For details, refer to the DDS WriterDataLifecycleQosPoli cy (p. 1071).

DDS WriterDataLifecycleQosPolicy::auto di spose unregistered -

instances (p. 1072) will always be forced to DDS BOOLEAN TRUE

(p. 298).

6.28.2.15 struct DDS RtpsReliableWriterProtocol t

DDS DiscoveryConﬁgQosPolicy::subscription writer

[read]

RTPS protocol-related conﬁguration settings for a built-in subscription writer.

For details, refer to the DDS DataWriterQos (p. 553)

6.28.2.16 struct DDS WriterDataLifecycleQosPolicy

DDS DiscoveryConﬁgQosPolicy::subscription writer -

data lifecycle [read]

Writer data lifecycle settings for a built-in subscription writer.

For details, refer to the DDS WriterDataLifecycleQosPoli cy (p. 1071).

DDS WriterDataLifecycleQosPolicy::auto di spose unregistered -

instances (p. 1072) will always be forced to DDS BOOLEAN TRUE

(p. 298).

6.28.2.17 DDS DiscoveryConﬁgBuiltinPluginKindMask DDS -

DiscoveryConﬁgQosPolicy::builtin discovery plugins

The kind mask for built-in discovery plugins.

There are several built-in discovery plugin. This mask enables the diﬀerent

plugins. Any plugin not enabled will not be created.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.28 DDS DiscoveryConﬁgQosPolicy Struct Reference 581

[default] DDS DISCOVERYCONFIG BUILTIN SDP (p. 425)

6.28.2.18 struct DDS RtpsReliableReaderProtocol t DDS -

DiscoveryConﬁgQosPolicy::participant message reader

[read]

RTPS protocol-related conﬁguration settings for a built-in participant message

reader.

For details, refer to the DDS DataReaderQos (p. 515)

6.28.2.19 struct DDS RtpsReliableWriterProtocol t DDS -

DiscoveryConﬁgQosPolicy::participant message writer

[read]

RTPS protocol-related conﬁguration settings for a built-in participant message

writer.

For details, refer to the DDS DataWriterQos (p. 553)

6.28.2.20 struct DDS PublishModeQosPolicy

DDS DiscoveryConﬁgQosPolicy::publication writer -

publish mode [read]

<<eXtension>> ( p. 199) Publish mode policy, PUBLISH MODE (p. 420).

Determines whether the Discovery DDSDataWriter (p. 1113) publishes data

synchronously or asynchronously and how.

6.28.2.21 struct DDS AsynchronousPublisherQosPolicy

DDS DiscoveryConﬁgQosPolicy::asynchronous publisher

[read]

<<eXtension>> ( p. 199) Asynchronous publishing settings for the Discovery

DDSPublisher (p. 1346) and all entities that are created by it.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

582 Class Documentation

6.29 DDS Discove ryQosPolicy Struct Reference

Conﬁgures the mechanism used by the middleware to automatically discover

and c onnect with new remote applications.

Public Attributes

struct DDS StringSeq enabled transports

The transports available for use by the Discovery mechanism.

struct DDS StringSeq initial peers

Determines the initial list of peers that will be contacted by the Discovery

mechanism to send announcements about the presence of this participant.

struct DDS StringSeq multicast receive addresses

Speciﬁes the multicast group addresses on which discovery-related meta-

traﬃc can be received by the DomainParticipant.

DDS Long metatraﬃc transport priority

The transport priority to use for the Discovery meta-traﬃc.

DDS Boolean accept unknown peers

Whether to accept a new participant that is not in the initial peers list.

6.29.1 Detailed Description

Conﬁgures the mechanism used by the middleware to automatically discover

and c onnect with new remote applications.

Entity:

DDSDomainParticipant (p. 1139)

Properties:

RxO (p. 340) = N/A

Changeable (p. 340) = NO (p. 340)

6.29.2 Usage

This QoS policy identiﬁes where on the network this application can potentially

discover other applications with which to communicate.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.29 DDS DiscoveryQosPolicy Struct Reference 583

The middleware will periodically send network packets to these locations, an-

nouncing itself to any remote applications that may be present, and will listen

for announcements from those applications.

This QoS policy is an extension to the DDS standard.

See also:

NDDS DISCOVERY PEERS (p. 388)

DDS DiscoveryConﬁgQosPolicy (p. 573)

6.29.3 Member Data Documentation

6.29.3.1 struct DDS StringSeq DDS DiscoveryQosPolicy::enabled -

transports [read]

The transports available for use by the Discovery mechanism.

Only these transports c an be used by the discovery mechanism to send meta-

traﬃc via the builtin endpoints (built-in DDSDataReader (p. 1087) and

DDSDataWriter (p. 1113)).

Also determines the unicast addresses on which the Discovery mechanism will

listen for meta-traﬃc. These along with the domain id and participant id

determine the unicast locators on which the Discovery mechanism c an receive

meta-data.

The memory for the strings in this sequence is managed according to the con-

ventions described in Conventions (p. 457). In particular, be careful to avoid

a situation in which RTI Connext alloc ates a string on your behalf and you

then reuse that string in such a way that RTI Connext believes it to have more

memory allocated to it than it actually does.

Alias names for the builtin transports are deﬁned in TRANSPORT -

BUILTIN (p. 396).

[default] Empty sequence. All the transports available to the DomainPartici-

pant are available for use by the Discovery mechanism.

[range] Sequence of non-null,non-empty strings.

6.29.3.2 struct DDS StringSeq DDS DiscoveryQosPolicy::initial -

peers [read]

Determines the initial list of peers that will be contacted by the Discovery

mechanism to send announcements about the presence of this participant.

If there is a remote peer DDSDomainParticipant (p. 1139) such as is de-

scribed in this list, it will become aware of this participant and will engage in

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

584 Class Documentation

the Discovery protocol to exchange meta-data with this participant.

Each element of this list must be a peer descriptor in the proper format (see

Peer Descriptor Format (p. 389)).

[default] See NDDS DISCOVERY PEERS (p. 388)

[range] Sequence of arbitrary length.

See also:

Peer Descriptor Format (p. 389)

DDSDomainParticipant::add peer() (p. 1199)

6.29.3.3 struct DDS StringSeq DDS -

DiscoveryQosPolicy::multicast receive addresses

[read]

Speciﬁes the multicast group addresses on which discovery-related meta-traﬃc

can be received by the DomainParticipant.

The multicast group addresses on which the Discovery me chanism will listen for

meta-traﬃc.

Each element of this list must be a valid multicast address (IPv4 or IPv6) in

the proper format (see Address Format (p. 390)).

The domain id determines the multicast port on which the Discovery mecha-

nism can receive meta-data.

If NDDS DISCOVERY PEERS does not contain a multicast address, then the

string s equence DDS DiscoveryQosPolicy::multicast receive addresses

(p. 584) is cleared and the RTI discovery proce ss will not listen for discovery

messages via multicast.

If NDDS DISCOVERY PEERS contains one or more multicast addresses, the

addresses will be stored in DDS DiscoveryQosPolicy::multicast receive -

addresses (p. 584), starting at element 0. They will be stored in the order they

appear NDDS DISCOVERY PEERS.

Note: Currently, RTI Connext will only listen for discovery traﬃc on the ﬁrst

multicast address (element 0) in DDS DiscoveryQosPolicy::multicast -

receive addresses (p. 584).

[default] See NDDS DISCOVERY PEERS (p. 388)

[range] Sequence of length [0,1], whose elements are multicast addresses. Cur-

rently only the ﬁrst multicast address (if any) is used. The rest are ignored.

See also:

Address Format (p. 390)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.29 DDS DiscoveryQosPolicy Struct Reference 585

6.29.3.4 DDS Long DDS DiscoveryQosPolicy::metatraﬃc -

transport priority

The transport priority to use for the Discovery meta-traﬃc.

The discovery metatraﬃc will be sent by the built-in DDSDataWriter

(p. 1113) using this transport priority.

[default] 0

6.29.3.5 DDS Boolean DDS DiscoveryQosPolicy::accept unknown -

peers

Whether to accept a new participant that is not in the initial pee rs list.

If DDS BOOLEAN FALSE (p. 299), the participant will only communicate

with those in the initial peers list and those added via DDSDomainPartici-

pant::add peer() (p. 1199).

If DDS BOOLEAN TRUE (p. 298), the participant will also communicate

with all discovered remote participants.

Note: If accept unknown p e ers is DDS BOOLEAN FALSE (p. 299) and

shared memory is disabled, applications on the same node will not communicate

if only ’localhost’ is speciﬁed in the p e ers list. If shared memory is disabled or

’shmem://’ is not speciﬁed in the peers list, to communicate with other applica-

tions on the same node through the loopback interface, you must put the ac tual

node address or hostname in NDDS DISCOVERY PEERS (p. 388).

[default] DDS BOOLEAN TRUE (p. 298)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

586 Class Documentation

6.30 DDS DomainParticipantFactoryQos

Struct Reference

QoS policies supported by a DDSDomainParticipantFactory (p. 1216).

Public Attributes

struct DDS EntityFactoryQosPolicy entity factory

Entity factory policy, ENTITY FACTORY ( p. 377).

struct DDS SystemResourceLimitsQosPolicy resource limits

<<eXtension>> (p. 199) System resource limits, SYSTEM -

RESOURCE LIMITS ( p. 415).

struct DDS ProﬁleQosPolicy proﬁle

<<eXtension>> (p. 199) Qos proﬁle policy, PROFILE ( p. 446).

struct DDS LoggingQosPolicy logging

<<eXtension>> (p. 199) Logging qos policy, LOGGING ( p. 450).

6.30.1 Detailed Description

QoS policies supported by a DDSDomainParticipantFactory (p. 1216).

Entity:

DDSDomainParticipantFactory (p. 1216)

See also:

QoS Policies (p. 331) and allowed ranges within each Qos.

6.30.2 Member Data Documentation

6.30.2.1 struct DDS EntityFactoryQosPolicy DDS -

DomainParticipantFactoryQos::entity factory

[read]

Entity factory policy, ENTITY FACTORY (p. 377).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.30 DDS DomainParticipantFactoryQos Struct Reference 587

6.30.2.2 struct DDS SystemResourceLimitsQosPolicy

DDS DomainParticipantFactoryQos::resource limits

[read]

<<eXtension>> ( p.

199) System resource limits, SYSTEM -

RESOURCE LIMITS (p. 415).

6.30.2.3 struct DDS ProﬁleQosPolicy DDS -

DomainParticipantFactoryQos::proﬁle

[read]

<<eXtension>> ( p. 199) Qos proﬁle policy, PROFILE (p. 446).

6.30.2.4 struct DDS LoggingQosPolicy DDS -

DomainParticipantFactoryQos::logging

[read]

<<eXtension>> ( p. 199) Logging qos policy, LOGGING (p. 450).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

588 Class Documentation

6.31 DDS DomainParticipantQos Struct Refer-

ence

QoS policies supported by a DDSDomainParticipant (p. 1139) entity.

Public Attributes

struct DDS UserDataQosPolicy user data

User data policy, USER DATA ( p. 345).

struct DDS EntityFactoryQosPolicy entity factory

Entity factory policy, ENTITY FACTORY ( p. 377).

struct DDS WireProtocolQosPolicy wire protocol

<<eXtension>> (p. 199) Wire Protocol policy , WIRE PROTOCOL

( p. 400).

struct DDS TransportBuilt inQosPolicy transport builtin

<<eXtension>> (p. 199) Transport Builtin policy, TRANSPORT -

BUILTIN ( p. 396).

struct DDS TransportUnicastQosPolicy default unicast

<<eXtension>> (p. 199) Default Unicast Transport policy, TRANS-

PORT UNICAST ( p. 383).

struct DDS DiscoveryQosPolicy discovery

<<eXtension>> (p. 199) Discovery policy, DISCOVERY ( p. 387).

struct DDS DomainParticipantResourceLimitsQosPolicy re-

source limits

<<eXtension>> (p. 199) Domain participant resource limits policy, DO-

MAIN PARTICIPANT RESOURCE LIMITS ( p. 416).

struct DDS Event QosPolicy event

<<eXtension>> (p. 199) Event policy, EVENT ( p. 417).

struct DDS ReceiverPoolQosPolicy receiver pool

<<eXtension>> (p. 199) Receiver pool policy, RECEIVER POOL

( p. 419).

struct DDS DatabaseQosPolicy database

<<eXtension>> (p. 199) Database policy, DATABASE ( p. 418).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.31 DDS DomainParticipantQos Struct Reference 589

struct DDS DiscoveryConﬁgQosPolicy discovery conﬁg

<<eXtension>> (p. 199) Discovery conﬁg policy, DISCOVERY -

CONFIG ( p. 423).

struct DDS PropertyQosPolicy property

<<eXtension>> (p. 199) Property policy, PROPERTY ( p. 436).

struct DDS EntityNameQosPolicy participant name

<<eXtension>> (p. 199) The participant name. ENTITY NAME

( p. 445)

struct DDS TransportMulticastMappingQosPolicy mul ticast -

mapping

<<eXtension>> (p. 199) The multicast mapping policy. TRANSPORT -

MULTICAST MAPPING ( p. 386)

struct DDS TypeSupportQosPolicy type support

<<eXtension>> (p. 199) Type support data, TYPESUPPORT ( p. 429).

6.31.1 Detailed Description

QoS policies supported by a DDSDomainParticipant (p. 1139) entity.

Certain members must be set in a consistent manner:

Length of DDS DomainParticipantQos::user data (p. 590) .value <=

DDS DomainParticipantQos::resource limi ts (p. 591) .participant user -

data max length

For DDS DomainParticipantQos::discovery conﬁg (p. 591) .publication -

writer

high watermark <= DDS DomainParticipantQos::resource limi ts

(p. 591) .lo cal writer allocation .max count heartbeats per max samples <=

DDS DomainParticipantQos::resource limi ts (p. 591) .local writer -

allocation.max count

For DDS DomainParticipantQos::discovery conﬁg (p. 591) .susc ription -

writer

high watermark <= DDS DomainParticipantQos::resource limi ts

(p. 591) .local reader allo c ation.max count heartbeats per max samples <=

DDS DomainParticipantQos::resource limi ts (p. 591) .local reader -

allocation.max count

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

590 Class Documentation

If any of the above are not true, DDSDomainParticipant::set qos (p. 1197)

and DDSDomainParticipant::set qos with proﬁle (p. 1198) and DDSDo-

mainParticipantFactory::set default participant qos (p. 1222) will fail

with DDS RETCODE INCONSISTENT POLICY (p. 315), and DDS-

DomainParticipantFactory::create participant (p. 1233) will fail.

Entity:

DDSDomainParticipant (p. 1139)

See also:

QoS Policies (p. 331) and allowed ranges within each Qos.

NDDS DISCOVERY PEERS (p. 388)

6.31.2 Member Data Documentation

6.31.2.1 struct DDS UserDataQosPolicy

DDS DomainParticipantQos::user data [read]

User data policy, USER DATA (p. 345).

6.31.2.2 struct DDS EntityFactoryQosPolicy

DDS DomainParticipantQos::entity factory [read]

Entity factory policy, ENTITY FACTORY (p. 377).

6.31.2.3 struct DDS WireProtocolQosPolicy

DDS DomainParticipantQos::wire protocol [read]

<<eXtension>> ( p. 199) Wire Protocol policy, WIRE PROTOCOL

(p. 400).

The wire protocol (RTPS) attributes associated with the participant.

6.31.2.4 struct DDS TransportBuiltinQosPolicy

DDS DomainParticipantQos::transport builtin [read]

<<eXtension>> ( p. 199) Transport Builtin policy, TRANSPORT -

BUILTIN (p. 396).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.31 DDS DomainParticipantQos Struct Reference 591

6.31.2.5 struct DDS TransportUnicastQosPolicy

DDS DomainParticipantQos::default unicast [read]

<<eXtension>> ( p. 199) Default Unicast Transport policy, TRANS-

PORT UNICAST (p. 383).

6.31.2.6 struct DDS DiscoveryQosPol icy

DDS DomainParticipantQos::discovery [read]

<<eXtension>> ( p. 199) Discovery policy, DISCOVERY (p. 387).

6.31.2.7 struct DDS DomainParticipantResourceLimitsQosPolicy

DDS DomainParticipantQos::resource limi ts [read]

<<eXtension>> ( p. 199) Domain participant resource limits policy, DO-

MAIN PA RTICIPANT RESOURCE LIMITS (p. 416).

6.31.2.8 struct DDS EventQosPolicy DDS -

DomainParticipantQos::event [read]

<<eXtension>> ( p.

199) Event policy, EVENT (p. 417).

6.31.2.9 struct DDS ReceiverPoolQosPolicy

DDS DomainParticipantQos::receiver pool [read]

<<eXtension>> ( p. 199) Receiver pool policy, RECEIVER POOL

(p. 419).

6.31.2.10 struct DDS DatabaseQosPolicy

DDS DomainParticipantQos::database [read]

<<eXtension>> ( p. 199) Database policy, DATABASE (p. 418).

6.31.2.11 struct DDS DiscoveryConﬁgQosPolicy

DDS DomainParticipantQos::discovery conﬁg [read]

<<eXtension>> ( p. 199) Discovery conﬁg policy, DISCOVERY CONFIG

(p. 423).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

592 Class Documentation

6.31.2.12 struct DDS PropertyQosPolicy

DDS DomainParticipantQos::property [read]

<<eXtension>> ( p. 199) Property policy, PROPERTY (p. 436).

6.31.2.13 struct DDS EntityNameQosPolicy

DDS DomainParticipantQos::participant name [read]

<<eXtension>> ( p. 199) The participant name. ENTITY NAME (p. 445)

6.31.2.14 struct DDS TransportMulticastMappingQosPolicy

DDS DomainParticipantQos::multicast mapping [read]

<<eXtension>> ( p. 199) The multicast mapping policy. TRANSPORT -

MULTICAST MAPPING (p. 386)

6.31.2.15 struct DDS TypeSupportQosPolicy

DDS DomainParticipantQos::type support [read]

<<eXtension>> ( p. 199) Type support data, TYPESUPPORT (p. 429).

Optional value that is passed to a type plugin’s on participant attached func-

tion.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.32 DDS DomainParticipantResourceLimitsQosPolicy Struct

Reference 593

6.32 DDS DomainParticipantResourceLimitsQosPolicy

Struct Reference

Various s ettings that conﬁgure how a DDSDomainParticipant (p. 1139) allo-

cates and uses physical memory for internal resources, including the maximum

sizes of various properties.

Public Attributes

struct DDS AllocationSettings t local writer allocation

Allocation settings applied to local DataWriters.

struct DDS AllocationSettings t local reader allocation

Allocation settings applied to local DataReaders.

struct DDS AllocationSettings t local publisher allocation

Allocation settings applied to local Publisher.

struct DDS AllocationSettings t local subscriber allocation

Allocation settings applied to local Subscriber.

struct DDS AllocationSettings t local topic allocation

Allocation settings applied to local Topic.

struct DDS AllocationSettings t remote writer all ocation

Allocation settings applied to remote DataWriters.

struct DDS AllocationSettings t remote reader all ocation

Allocation settings applied to remote DataReaders.

struct DDS AllocationSettings t remote participant allocation

Allocation settings applied to remote DomainParticipants.

struct DDS AllocationSettings t matching writer reader pair -

allocation

Allocation settings applied to matching local writer and remote/local reader

pairs.

struct DDS AllocationSettings t matching reader writer pair -

allocation

Allocation settings applied to matching local reader and remote/local writer

pairs.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

594 Class Documentation

struct DDS AllocationSettings t ignored entity allocation

Allocation settings applied to ignored entities.

struct DDS AllocationSettings t content ﬁltered topic -

allocation

Allocation settings applied to content ﬁltered topic.

struct DDS AllocationSettings t content ﬁlter allocation

Allocation settings applied to content ﬁlter.

struct DDS AllocationSettings t read condition allocation

Allocation settings applied to read condition pool.

struct DDS AllocationSettings t query condition allocation

Allocation settings applied to query condition pool.

struct DDS AllocationSettings t outstanding asynchronous -

sample allocation

Allocation settings applied to the maximum number of samples (from all

DDSDataWriter ( p. 1113)) waiting to be asynchronously written.

struct DDS AllocationSettings t ﬂow controller allocation

Allocation settings applied to ﬂow controllers.

DDS Long local writer hash buckets

Hash Buckets settings applied to local DataWriters.

DDS Long local reader hash buckets

Number of hash buckets for local DataReaders.

DDS Long local publisher hash buckets

Number of hash buckets for local Publisher.

DDS Long local subscriber hash buckets

Number of hash buckets for local Subscriber.

DDS Long local topic hash buckets

Number of hash buckets for local Topic.

DDS Long remote writer hash buckets

Number of hash buckets for remote DataWriters.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.32 DDS DomainParticipantResourceLimitsQosPolicy Struct

Reference 595

DDS Long remote reader hash buckets

Number of hash buckets for remote DataReaders.

DDS Long remote participant hash buckets

Number of hash buckets for remote DomainParticipants.

DDS Long matching writer reader pair hash buckets

Number of hash buckets for matching local writer and remote/local reader

pairs.

DDS Long matching reader writer pair hash buckets

Number of hash buckets for matching local reader and remote/local writer

pairs.

DDS Long ignored entity hash buckets

Number of hash buckets for ignored entities.

DDS Long content ﬁlt ered topic hash buckets

Number of hash buckets for content ﬁltered topics.

DDS Long content ﬁlt er hash buckets

Number of hash buckets for content ﬁlters.

DDS Long ﬂow controller hash buckets

Number of hash buckets for ﬂow controllers.

DDS Long max gather destinations

Maximum number of destinations per RTI Connext send.

DDS Long participant user data max length

Maximum length of user data in DDS DomainParticipantQos ( p. 588)

and DDS ParticipantBuiltinTopicData ( p. 816).

DDS Long topic data max length

Maximum length of topic data in DDS TopicQos ( p. 965), DDS -

TopicBuiltinTopicData ( p. 958), DDS PublicationBuiltinTopicData

( p. 839) and DDS SubscriptionBuiltinTopicData ( p. 936).

DDS Long publisher group data max length

Maximum length of group data in DDS PublisherQos ( p. 851) and DDS -

PublicationBuiltinTopicData ( p. 839).

DDS Long subscriber group data max length

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

596 Class Documentation

Maximum length of group data in DDS SubscriberQos ( p. 934) and

DDS SubscriptionBuiltinTopicData ( p. 936).

DDS Long writer user data max length

Maximum length of user data in DDS DataWriterQos ( p. 553) and

DDS PublicationBuiltinTopicData ( p. 839).

DDS Long reader user data max length

Maximum leng th of user data in DDS DataReaderQos ( p. 515) and

DDS SubscriptionBuiltinTopicData ( p. 936).

DDS Long max partitions

Maximum number of partition name strings allowable in a DDS -

PartitionQosPolicy ( p. 820).

DDS Long max partition cumulative characters

Maximum number of combined characters allowable in all partition names

in a DDS PartitionQosPolicy ( p. 820).

DDS Long type code max serialized length

Maximum size of serialized string for type code.

DDS Long type object max serialized length

DDS Long serialized type object dynamic allocation threshold

DDS Long type object max deserialized length

DDS Long deserialized type object dynamic allocation -

threshold

DDS Long contentﬁlter property max length

This ﬁeld is the maximum length of all data related to a Content-ﬁltered

topic.

DDS Long channel seq max length

Maximum number of channels that can be speciﬁed in DDS -

MultiChannelQosPolicy ( p. 796) for MultiChannel DataWriters.

DDS Long channel ﬁlter expression max length

Maximum length of a channel DDS ChannelSettings t::ﬁlter expression

( p. 486) in a MultiChannel DataWriter.

DDS Long participant property list max length

Maximum number of properties associated with the DDSDomainPartici-

pant ( p. 1139).

DDS Long participant property string max length

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.32 DDS DomainParticipantResourceLimitsQosPolicy Struct

Reference 597

Maximum string length of the properties associated with the DDSDomain-

Participant ( p. 1139).

DDS Long writer property list max length

Maximum number of properties associated with a DDSDataWriter

( p. 1113).

DDS Long writer property string max length

Maximum string length of the properties associated with a DDSDataWriter

( p. 1113).

DDS Long reader property list max length

Maximum number of properties associated with a DDSDataReader

( p. 1087).

DDS Long reader property string max length

Maximum string length of the properties associated with a DDSDataReader

( p. 1087).

DDS Long max endpoint groups

Maximum number of DDS EndpointGroup t ( p. 731) allowable in a

DDS AvailabilityQosPolicy ( p. 471).

DDS Long max endpoint group cumulative characters

Maximum number of combined role name characters allowable in all DDS -

EndpointGroup t ( p. 731) in a DDS AvailabilityQosPolicy ( p. 471).

6.32.1 Detailed Description

Various s ettings that conﬁgure how a DDSDomainParticipant (p. 1139) allo-

cates and uses physical memory for internal resources, including the maximum

sizes of various properties.

This QoS policy sets maximum size limits on variable-length parameters used

by the participant and its contained Entities. It also controls the initial and

maximum sizes of data structures used by the participant to store informa-

tion about locally-created and remotely-discovered entities (such as DataWrit-

ers/DataReaders), as well as parameters used by the internal database to size

the hash tables it uses.

By default, a DDSDomainParticipant (p. 1139) is allowed to dynamically

allocate memory as needed as users create local Entities such as DDS-

DataWriter (p. 1113) and DDSDataReader (p. 1087) objects or as the par-

ticipant discovers new applications. By setting ﬁxed values for the maximum

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

598 Class Documentation

parameters in this QoS policy, you can bound the memory that can be al-

located by a DDSDomainParticipant (p. 1139). In addition, by setting the

initial values to the maximum values, you can prevent DomainParticipants from

allocating memory after the initialization period.

The maximum sizes of diﬀerent variable-length parameters such as the number

of partitions that can b e stored in the DDS PartitionQosPolicy (p. 820),

the maximum length of data store in the DDS UserDataQosPolicy (p. 1048)

and DDS GroupDataQosPolicy (p. 755), and many others can be changed

from their defaults using this QoS policy. However, it is important that all

DomainParticipants that need to communicate with each other use the same set

of maximum values. Otherwise, when these parameters are propagated from one

DDSDomainParticipant (p. 1139) to another, a DDSDomainParticipant

(p. 1139) with a smaller maximum length may reject the parameter, resulting

in an error.

An important parameter in this QoS policy that is often changed

by users is DDS DomainParticipantResourceLimitsQosPolicy::type -

code max serialized length (p. 608).

This QoS policy is an extension to the DDS standard.

Entity:

DDSDomainParticipant (p. 1139)

Properties:

RxO (p. 340) = N/A

Changeable (p. 340) = NO (p. 340)

6.32.2 Member Data Documentation

6.32.2.1 struct DDS AllocationSettings t

DDS DomainParticipantResourceLimitsQosPolicy::local -

writer allocation [read]

Allocation settings applied to local DataWriters.

[default] initial count = 16; max count = DDS LENGTH UNLIMITED

(p. 371); incremental count = -1

[range] See allowed ranges in struct DDS AllocationSettings t (p. 464)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.32 DDS DomainParticipantResourceLimitsQosPolicy Struct

Reference 599

6.32.2.2 struct DDS AllocationSettings t

DDS DomainParticipantResourceLimitsQosPolicy::local -

reader allocation [read]

Allocation settings applied to local DataReaders.

[default] initial count = 16; max count = DDS LENGTH UNLIMITED

(p. 371); incremental count = -1

[range] See allowed ranges in struct DDS AllocationSettings t (p. 464)

6.32.2.3 struct DDS AllocationSettings t

DDS DomainParticipantResourceLimitsQosPolicy::local -

publisher allocation [read]

Allocation settings applied to local Publisher.

[default] initial count = 4; max count = DDS LENGTH UNLIMITED

(p. 371); incremental count = -1

[range] See allowed ranges in struct DDS AllocationSettings t (p. 464)

6.32.2.4 struct DDS AllocationSettings t

DDS DomainParticipantResourceLimitsQosPolicy::local -

subscriber allocation [read]

Allocation settings applied to local Subscriber.

[default] initial

count = 4; max count = DDS LENGTH UNLIMITED

(p. 371); incremental count = -1

[range] See allowed ranges in struct DDS AllocationSettings t (p. 464)

6.32.2.5 struct DDS AllocationSettings t

DDS DomainParticipantResourceLimitsQosPolicy::local -

topic allocation [read]

Allocation settings applied to local Topic.

[default] initial count = 16; max count = DDS LENGTH UNLIMITED

(p. 371); incremental count = -1

[range] See allowed ranges in struct DDS AllocationSettings t (p. 464)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

600 Class Documentation

6.32.2.6 struct DDS AllocationSettings t DDS -

DomainParticipantResourceLimitsQosPolicy::remote -

writer allocation [read]

Allocation settings applied to remote DataWriters.

Remote DataWriters include all DataWriters, both local and remote.

[default] initial count = 64; max count = DDS LENGTH UNLIMITED

(p. 371); incremental count = -1

[range] See allowed ranges in struct DDS AllocationSettings t (p. 464)

6.32.2.7 struct DDS AllocationSettings t DDS -

DomainParticipantResourceLimitsQosPolicy::remote -

reader allocation [read]

Allocation settings applied to remote DataReaders.

Remote DataReaders include all DataReaders, both local and remote.

[default] initial count = 64; max count = DDS LENGTH UNLIMITED

(p. 371); incremental count = -1

[range] See allowed ranges in struct DDS AllocationSettings t (p. 464)

6.32.2.8 struct DDS AllocationSettings t DDS -

DomainParticipantResourceLimitsQosPolicy::remote -

participant allocation [read]

Allocation settings applied to remote DomainParticipants.

Remote DomainParticipants include all DomainParticipants, both local and re-

mote.

[default] initial count = 16; max count = DDS LENGTH UNLIMITED

(p. 371); incremental count = -1

[range] See allowed ranges in struct DDS AllocationSettings t (p. 464)

6.32.2.9 struct DDS AllocationSettings t DDS -

DomainParticipantResourceLimitsQosPolicy::matching -

writer reader pair allocation [read]

Allocation settings applied to matching local writer and remote/local reader

pairs.

[default] initial count = 32; max count = DDS LENGTH UNLIMITED

(p. 371); incremental count = -1

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.32 DDS DomainParticipantResourceLimitsQosPolicy Struct

Reference 601

[range] See allowed ranges in struct DDS AllocationSettings t (p. 464)

6.32.2.10 struct DDS AllocationSettings t DDS -

DomainParticipantResourceLimitsQosPolicy::matching -

reader writer pair allocation [read]

Allocation settings applied to matching local reader and remote/local writer

pairs.

[default] initial count = 32; max count = DDS LENGTH UNLIMITED

(p. 371); incremental count = -1

[range] See allowed ranges in struct DDS AllocationSettings t (p. 464)

6.32.2.11 struct DDS AllocationSettings t DDS -

DomainParticipantResourceLimitsQosPolicy::ignored -

entity allocation [read]

Allocation settings applied to ignored entities.

[default] initial count = 8; max count = DDS LENGTH UNLIMITED

(p. 371); incremental count = -1

[range] See allowed ranges in struct DDS AllocationSettings t (p. 464)

6.32.2.12 struct DDS AllocationSettings t DDS -

DomainParticipantResourceLimitsQosPolicy::content -

ﬁltered topic allocation [read]

Allocation settings applied to content ﬁltered topic.

[default] initial count = 4; max count = DDS LENGTH UNLIMITED

(p. 371); incremental count = -1

[range] See allowed ranges in struct DDS AllocationSettings t (p. 464)

6.32.2.13 struct DDS AllocationSettings t DDS -

DomainParticipantResourceLimitsQosPolicy::content -

ﬁlter allocation [read]

Allocation settings applied to content ﬁlter.

[default] initial count = 4; max count = DDS LENGTH UNLIMITED

(p. 371); incremental count = -1

[range] See allowed ranges in struct DDS AllocationSettings t (p. 464)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

602 Class Documentation

6.32.2.14 struct DDS AllocationSettings t

DDS DomainParticipantResourceLimitsQosPolicy::read -

condition allocation [read]

Allocation settings applied to read condition pool.

[default] initial count = 4; max count = DDS LENGTH UNLIMITED

(p. 371), incremental count = -1

[range] See allowed ranges in struct DDS AllocationSettings t (p. 464)

6.32.2.15 struct DDS AllocationSettings t DDS -

DomainParticipantResourceLimitsQosPolicy::query -

condition allocation [read]

Allocation settings applied to query condition pool.

[default] initial count = 4; max count = DDS LENGTH UNLIMITED

(p. 371), incremental count = -1

[range] See allowed ranges in struct DDS AllocationSettings t (p. 464)

6.32.2.16 struct DDS AllocationSettings t DDS -

DomainParticipantResourceLimitsQosPolicy::outstanding -

asynchronous

sample allocation [read]

Allocation settings applied to the maximum number of samples (from all DDS-

DataWriter (p. 1113)) waiting to be asynchronously written.

[default] initial count = 64; max count = DDS LENGTH UNLIMITED

(p. 371), incremental count = -1

[range] See allowed ranges in struct DDS AllocationSettings t (p. 464)

6.32.2.17 struct DDS AllocationSettings t

DDS DomainParticipantResourceLimitsQosPolicy::ﬂow -

controller allocation [read]

Allocation settings applied to ﬂow controllers.

[default] initial count = 4; max count = DDS LENGTH UNLIMITED

(p. 371), incremental count = -1

[range] See allowed ranges in struct DDS AllocationSettings t (p. 464)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.32 DDS DomainParticipantResourceLimitsQosPolicy Struct

Reference 603

6.32.2.18 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::local -

writer hash buckets

Hash Buckets settings applied to local DataWriters.

[default] 4

[range] [1, 10000]

6.32.2.19 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::local -

reader hash buckets

Number of hash buckets for local DataReaders.

[default] 4

[range] [1, 10000]

6.32.2.20 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::local -

publisher hash buckets

Number of hash buckets for local Publisher.

[default] 1

[range] [1, 10000]

6.32.2.21 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::local -

subscriber hash buckets

Number of hash buckets for local Subscriber.

[default] 1

[range] [1, 10000]

6.32.2.22 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::local -

topic hash buckets

Number of hash buckets for local Topic.

[default] 4

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

604 Class Documentation

[range] [1, 10000]

6.32.2.23 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::remote -

writer hash buckets

Number of hash buckets for remote DataWriters.

Remote DataWriters include all DataWriters, both local and remote.

[default] 16

[range] [1, 10000]

6.32.2.24 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::remote -

reader hash buckets

Number of hash buckets for remote DataReaders.

Remote DataReaders include all DataReaders, both local and remote.

[default] 16

[range] [1, 10000]

6.32.2.25 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::remote -

participant

hash buckets

Number of hash buckets for remote DomainParticipants.

Remote DomainParticipants include all DomainParticipants, both local and re-

mote.

[default] 4

[range] [1, 10000]

6.32.2.26 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::matching -

writer reader pair hash buckets

Number of hash buckets for matching local writer and remote/local reader pairs.

[default] 32

[range] [1, 10000]

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.32 DDS DomainParticipantResourceLimitsQosPolicy Struct

Reference 605

6.32.2.27 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::matching -

reader writer pair hash buckets

Number of hash buckets for matching local reader and remote/local writer pairs.

[default] 32

[range] [1, 10000]

6.32.2.28 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::ignored -

entity hash buckets

Number of hash buckets for ignored entities.

[default] 1

[range] [1, 10000]

6.32.2.29 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::content -

ﬁltered topic hash buckets

Number of hash buckets for content ﬁltered topics.

[default] 1

[range] [1, 10000]

6.32.2.30 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::content -

ﬁlter hash buckets

Number of hash buckets for content ﬁlters.

[default] 1

[range] [1, 10000]

6.32.2.31 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::ﬂow -

controller hash buckets

Number of hash buckets for ﬂow controllers.

[default] 1

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

606 Class Documentation

[range] [1, 10000]

6.32.2.32 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::max -

gather destinations

Maximum number of destinations per RTI Connext send.

When RTI Connext sends out a message, it has the capability to send to multiple

destinations to be more eﬃcient. The maximum number of destinations per RTI

Connext send is speciﬁed by max gather destinations.

[default] 8

[range] [4, 1 million]

6.32.2.33 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::participant -

user data max length

Maximum length of user data in DDS DomainParticipantQos (p. 588) and

DDS ParticipantBuiltinTopicData (p. 816).

[default] 256

[range] [0,0x7ﬀﬀﬀf]

6.32.2.34 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::topic data -

max length

Maximum length of topic data in DDS TopicQos (p. 965), DDS -

TopicBuiltinTopicData (p. 958), DDS PublicationBuiltinTopicData

(p. 839) and DDS SubscriptionBuiltinTopicData (p. 936).

[default] 256

[range] [0,0x7ﬀﬀﬀf]

6.32.2.35 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::publisher -

group data max length

Maximum length of group data in DDS PublisherQos (p. 851) and DDS -

PublicationBuiltinTopicData (p. 839).

[default] 256

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.32 DDS DomainParticipantResourceLimitsQosPolicy Struct

Reference 607

[range] [0,0x7ﬀﬀﬀf]

6.32.2.36 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::subscriber -

group data max length

Maximum length of group data in DDS SubscriberQos (p. 934) and DDS -

SubscriptionBuiltinTopicData (p. 936).

[default] 256

[range] [0,0x7ﬀﬀﬀf]

6.32.2.37 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::writer -

user data max length

Maximum length of user data in DDS DataWriterQos (p. 553) and DDS -

PublicationBuiltinTopicData (p. 839).

[default] 256

[range] [0,0x7ﬀﬀﬀf]

6.32.2.38 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::reader -

user data max length

Maximum length of user data in DDS DataReaderQos (p. 515) and DDS -

SubscriptionBuiltinTopicData (p. 936).

[default] 256

[range] [0,0x7ﬀﬀﬀf]

6.32.2.39 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::max -

partitions

Maximum number of partition name strings allowable in a DDS -

PartitionQosPolicy (p. 820).

This setting is made on a per DomainParticipant basis; it cannot be set individ-

ually on a per Publisher/Subscriber basis. However, the limit is enforced and

applies per Publisher/Subscriber.

This value cannot exceed 64.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

608 Class Documentation

[default] 64

[range] [0,64]

6.32.2.40 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::max -

partition cumulative characters

Maximum number of combined characters allowable in all partition names in a

DDS PartitionQosPolicy (p. 820).

The maximum number of combined characters should account for a terminating

NULL (’\0’) character for each partition name string.

This setting is made on a per DomainParticipant basis; it cannot be set individ-

ually on a per Publisher/Subscriber basis. However, the limit is enforced and

applies per Publisher/Subscriber.

This value cannot exceed 256.

[default] 256

[range] [0,256]

6.32.2.41 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::type code -

max serialized length

Maximum size of serialized string for type code.

This parameter limits the size of the type code that a DDSDomainPartici-

pant (p. 1139) is able to store and propagate for user data types. Type codes

can be used by external applications to understand user data types without

having the data type predeﬁned in compiled form. However, since type codes

contain all of the information of a data structure, including the strings that

deﬁne the names of the members of a structure, complex data structures can

result in type codes larger than the default maximum of 2048 bytes. So it is

common for users to set this parameter to a larger value. However, as with all

parameters in this QoS policy deﬁning maximum size s for variable-length ele-

ments, all DomainParticipants in the same domain should use the same value

for this parameter.

[default] 2048

[range] [0,0xﬀﬀ]

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.32 DDS DomainParticipantResourceLimitsQosPolicy Struct

Reference 609

6.32.2.42 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::type -

object max serialized length

6.32.2.43 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::serialized -

type object dynamic allocation threshold

6.32.2.44 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::type -

object max deserialized length

6.32.2.45 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::deserialized -

type object dynamic allocation threshold

6.32.2.46 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::contentﬁlter -

property max length

This ﬁeld is the maximum length of all data related to a Content-ﬁltered topic.

This is the sum of the length of the content ﬁlter name, the length of the related

topic name, the length of the ﬁlter expression, the length of the ﬁlter parameters,

and the length of the ﬁlter name. The maximum number of combined characters

should ac count for a terminating NULL (’\0’) character for each string.

[default] 256

[range] [0,0xﬀﬀ]

6.32.2.47 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::channel -

seq max length

Maximum number of channels that can be speciﬁed in DDS -

MultiChannelQosPolicy (p. 796) for MultiChannel DataWriters.

[default] 32

[range] [0,0xﬀﬀ]

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

610 Class Documentation

6.32.2.48 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::channel -

ﬁlter expression max length

Maximum length of a channel DDS ChannelSettings t::ﬁlter expression

(p. 486) in a MultiChannel DataWriter.

The length should account for a terminating NULL (’\0’) character.

[default] 256

[range] [0,0xﬀﬀ]

6.32.2.49 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::participant -

property list max length

Maximum number of properties associated with the DDSDomainParticipant

(p. 1139).

[default] 32

[range] [0,0xﬀﬀ]

6.32.2.50 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::participant -

property string max length

Maximum string length of the properties associated with the DDSDomain-

Participant (p. 1139).

The string length is deﬁned as the cumulative length in bytes, including the

null terminating characters, of all the pair (name,value) associated with the

DDSDomainParticipant (p. 1139) properties.

[default] 1024

[range] [0,0xﬀﬀ]

6.32.2.51 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::writer -

property list max length

Maximum number of properties associated with a DDSDataWriter (p. 1113).

[range] [0,0xﬀﬀ]

[default] 32

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.32 DDS DomainParticipantResourceLimitsQosPolicy Struct

Reference 611

6.32.2.52 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::writer -

property string max length

Maximum string length of the properties associated with a DDSDataWriter

(p. 1113).

The string length is deﬁned as the cumulative length in bytes, including the

null terminating characters, of all the pair (name,value) associated with the

DDSDataWriter (p. 1113) properties.

[default] 1024

[range] [0,0xﬀﬀ]

6.32.2.53 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::reader -

property list max length

Maximum number of properties ass ociated with a DDSDataReader (p. 1087).

[default] 32

[range] [0,0xﬀﬀ]

6.32.2.54 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::reader -

property string max length

Maximum string length of the properties associated with a DDSDataReader

(p. 1087).

The string length is deﬁned as the cumulative length in bytes, including the null

terminating characters, of all the pair (name,value) associated with a DDS-

DataReader (p. 1087) properties.

[default] 1024

[range] [0,0xﬀﬀ]

6.32.2.55 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::max -

endpoint groups

Maximum number of DDS EndpointGroup t (p. 731) allowable in a DDS -

AvailabilityQosPolicy (p. 471).

[default] 32

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

612 Class Documentation

[range] [0,65535]

6.32.2.56 DDS Long DDS -

DomainParticipantResourceLimitsQosPolicy::max -

endpoint group cumulative characters

Maximum number of combined role name characters allowable in all DDS -

EndpointGroup t (p. 731) in a DDS AvailabilityQosPolicy (p. 471).

The maximum number of combined characters should account for a terminating

NULL character for each role name string.

[default] 1024

[range] [0,65535]

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.33 DDS DoubleSeq Struct Reference 613

6.33 DDS DoubleSeq Struct Re fere nce

Instantiates FooSeq (p. 1494) < DDS Double (p. 300) >.

6.33.1 Detailed Description

Instantiates FooSeq (p. 1494) < DDS Double (p. 300) >.

Instantiates:

<<generic>> ( p. 199) FooSeq (p. 1494)

See also:

DDS Double (p. 300)

FooSeq (p. 1494)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

614 Class Documentation

6.34 DDS DurabilityQosPolicy Struct Refer-

ence

This QoS policy speciﬁes whether or not RTI Connext will store and deliver

previously published data samples to new DDSDataReader (p. 1087) entities

that join the network later.

Public Attributes

DDS DurabilityQosPolicyKind kind

The kind of durability.

DDS Boolean direct communication

<<eXtension>> (p. 199) Indicates whether or not a TRANSIENT or

PERSISTENT DDSDataReader ( p. 1087) should receive samples directly

from a TRANSIENT or PERSISTENT DDSDataWriter ( p. 1113)

6.34.1 Detailed Description

This QoS policy speciﬁes whether or not RTI Connext will store and deliver

previously published data samples to new DDSDataReader (p. 1087) entities

that join the network later.

Entity:

DDSTopic (p. 1419), DDSDataReader (p. 1087), DDSDataWriter

(p. 1113)

Status:

DDS OFFERED INCOMPATIBLE QOS STATUS (p. 323),

DDS REQUESTED INCOMPATIBLE QOS STATUS (p. 323)

Properties:

RxO (p. 340) = YES

Changeable (p. 340) = UNTIL ENABLE (p. 340)

See also:

DURABILITY SERV ICE (p. 370)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.34 DDS DurabilityQosPolicy Struct Reference 615

6.34.2 Usage

It is possible for a DDSDataWriter (p. 1113) to start publishing data before

all (or any) DDSDataReader (p. 1087) entities have joined the network.

Moreover, a DDSDataReader (p. 1087) that joins the network after some data

has been written could potentially be interested in accessing the mos t current

values of the data, as well as potentially some history.

This policy makes it possible for a late-joining DDSDataReader (p. 1087) to

obtain previously published s amples.

By helping to ensure that DataReaders get all data that was sent by DataWrit-

ers, regardless of when it was sent, using this QoS policy can increase system

tolerance to failure conditions.

Note that although related, this does not strictly control what data RTI Connext

will maintain internally. That is, RTI Connext may choose to maintain some

data for its own purposes (e.g., ﬂow control) and yet not make it available

to late-joining readers if the DURABILITY (p.

348) policy is set to DDS -

VOLATILE DURABILITY QOS (p. 349).

6.34.2.1 Transient and Persistent Durability

For the purpose of implementing the DURABILITY QoS kind TRAN-

SIENT or PERSISTENT, RTI Connext behaves as if for each Topic that

has DDS DurabilityQosPolicy::kind (p. 617) of DDS TRANSIENT -

DURABILITY QOS (p. 349) or DDS PERSISTENT DURABILITY -

QOS (p. 349) there is a corresponding ”built-in” DDSDataReader (p. 1087)

and DDSDataWriter (p. 1113) conﬁgured with the same DURABILITY kind.

In other words, it is as if somewhere in the system, independent of the origi-

nal DDSDataWriter (p. 1113), there is a built-in durable DDSDataReader

(p. 1087) subscribing to that Topic and a built-in durable DataWriter re-

publishing it as needed for the new subscribers that join the system. This

functionality is provided by the RTI Persistence Service.

The Persistence Service can conﬁgure itself based on the QoS of your appli-

cation’s DDSDataWriter (p.

1113) and DDSDataReader (p. 1087) entities.

For each transient or persistent DDSTopic (p. 1419), the built-in ﬁctitious Per-

sistence Service DDSDataReader (p. 1087) and DDSDataWriter (p. 1113)

have their QoS conﬁgured from the QoS of your application’s DDSDataWriter

(p. 1113) and DDSDataReader (p. 1087) entities that communicate on that

DDSTopic (p. 1419).

For a given DDSTopic (p. 1419), the usual request/oﬀered semantics apply

to the matching between any DDSDataWriter (p. 1113) in the domain that

writes the DDSTopic (p. 1419) and the built-in transient/persistent DDS-

DataReader (p. 1087) for that DDSTopic (p. 1419); similarly for the built-

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

616 Class Documentation

in transient/persistent DDSDataWriter (p. 1113) for a DDSTopic (p. 1419)

and any DDSDataReader (p. 1087) for the DDSTopic (p. 1419). As a con-

sequence, a DDSDataWriter (p. 1113) that has an incompatible QoS will not

send its data to the RTI Persistence Service, and a DDSDataReader (p. 1087)

that has an incompatible QoS will not get data from it.

Incompatibilities between local DDSDataReader (p. 1087) and DDS-

DataWriter (p. 1113) entities and the corresponding ﬁctitious built-

in transient/persistent entities cause the DDS REQUESTED -

INCOMPATIBLE QOS STATUS (p. 323) and DDS OFFERED -

INCOMPATIBLE QOS STATUS (p. 323) to change and the corresponding

Listener invocations and/or signaling of DDSCondition (p. 1075) objects as

they would with your application’s own entities.

The value of DDS DurabilityServiceQosPolicy::service cleanup delay

(p. 619) controls when RTI Persistence Service is able to remove all information

regarding a data instances.

Information on a data instance is maintained until the following conditions are

met:

1. The instance has been explicitly disposed (instance state = NOT ALIVE -

DISPOSED),

and

2. While in the NOT ALIVE DISPOSED state, the system detects that there

are no more ’live’ DDSDataWriter (p. 1113) entities writing the instance.

That is, all existing writers either unregister the instance (call unregister) or

lose their liveliness,

and

3. A time interval longer that DDS DurabilityServiceQosPolicy::service -

cleanup delay (p. 619) has elapsed since the moment RTI Connext detected

that the previous two conditions were met.

The utility of DDS DurabilityServiceQosPolicy::service cleanup delay

(p. 619) is apparent in the situation where an application disposes an instance

and it crashes before it has a chance to complete additional tasks related to

the disposition. Upon restart, the application may ask for initial data to regain

its state and the delay introduced by the service cleanup delay will allow the

restarted application to receive the information on the disposed instance and

complete the interrupted tasks.

6.34.3 Compatibility

The value oﬀered is considered compatible w ith the value requested if and

only if the inequality oﬀered kind >= requested kind evaluates to ’TRUE’.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.34 DDS DurabilityQosPolicy Struct Reference 617

For the purp ose s of this inequality, the values of DURABILITY kind are con-

sidered ordered such that DDS VOLATILE DURABILITY QOS (p. 349)

< DDS TRANSIENT LOCAL DURABILITY QOS (p. 349) < DDS -

TRANSIENT DURABILITY QOS (p. 349) < DDS PERSISTENT -

DURABILITY QOS (p. 349).

6.34.4 Member Data Documentation

6.34.4.1 DDS DurabilityQosPolicyKind DDS -

DurabilityQosPolicy::kind

The kind of durability.

[default] DDS VOLATILE DURABILITY QOS (p. 349)

6.34.4.2 DDS Boolean DDS DurabilityQosPolicy::direct -

communication

<<eXtension>> ( p. 199) Indicates whether or not a TRANSIENT or PER-

SISTENT DDSDataReader (p. 1087) should receive samples directly from a

TRANSIENT or PERSISTENT DDSDataWriter (p. 1113)

When direct communication is set to DDS BOOLEAN TRUE (p. 298), a

TRANSIENT or PERSISTENT DDSDataReader (p. 1087) will receive sam-

ples from both the original DDSDataWriter (p. 1113) conﬁgured with TRAN-

SIENT or PERSISTENT durability and the DDSDataWriter (p. 1113) cre-

ated by the persistence service. This peer-to-peer communication pattern pro-

vides low latency between end-points.

If the same sample is received from the original DDSDataWriter (p. 1113)

and the persistence service, the middleware will discard the duplicate.

When direct communication is set to DDS BOOLEAN FALSE (p. 299), a

TRANSIENT or PERSISTENT DDSDataReader (p. 1087) will only receive

samples from the DDSDataWriter (p. 1113) created by the pe rsistence service.

This brokered communication pattern provides a way to guarantee eventual

consistency.

[default] DDS BOOLEAN TRUE (p. 298)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

618 Class Documentation

6.35 DDS DurabilityServiceQosPolicy Struct

Reference

Various settings to conﬁgure the external RTI Persistence Service used by

RTI Connext for DataWriters with a DDS DurabilityQosPolicy (p. 614)

setting of DDS PERSISTENT DURABILITY QOS (p. 349) or DDS -

TRANSIENT DURABILITY QOS (p. 349).

Public Attributes

struct DDS Duration t service cleanup delay

[Not supported (optional)] Controls when the service is able to remove

all information regarding a data instances.

DDS HistoryQosPolicyKind history kind

The kind of history to apply in recouping durable data.

DDS Long history depth

Part of history QoS policy t o apply when feeding a late joiner.

DDS Long max samples

Part of resource limits QoS policy to apply when feeding a late joiner.

DDS Long max instances

Part of resource limits QoS policy to apply when feeding a late joiner.

DDS Long max samples per instance

Part of resource limits QoS policy to apply when feeding a late joiner.

6.35.1 Detailed Description

Various settings to conﬁgure the external RTI Persistence Service used by

RTI Connext for DataWriters with a DDS DurabilityQosPolicy (p. 614)

setting of DDS PERSISTENT DURABILITY QOS (p. 349) or DDS -

TRANSIENT DURABILITY QOS (p. 349).

Entity:

DDSTopic (p. 1419), DDSDataWriter (p. 1113)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.35 DDS DurabilityServiceQosPolicy Struct Refe rence 619

Properties:

RxO (p. 340) = NO

Changeable (p. 340) = UNTIL ENABLE (p. 340)

See also:

DURABILITY (p. 348)

HISTORY (p. 367)

RESOURCE LIMITS (p. 371)

6.35.2 Usage

When a DataWriter’s DDS DurabilityQosPolicy::kind (p. 617) is DDS -

PERSISTENT DURABILITY QOS (p. 349) or DDS TRANSIENT -

DURABILITY QOS (p. 349), an external se rvice, the RTI Persistence Ser-

vice, is used to store and possibly forward the data sent by the DDS-

DataWriter (p. 1113) to DDSDataReader (p. 1087) objects that are created

after the data was initially sent.

This QoS policy is used to conﬁgure certain parameters of the Persistence Service

when it operates on the behalf of the DDSDataWriter (p. 1113), such as how

much data to store. For example, it conﬁgures the HISTORY (p. 367) and

the RESOURCE LIMITS (p. 371) used by the ﬁctitious DataReader and

DataWriter used by the Persistence Service. Note, however, that the Persistence

Service itself may be conﬁgured to ignore these values and instead use values

from its own conﬁguration ﬁle.

6.35.3 Member Data Documentation

6.35.3.1 struct DDS Duration t DDS -

DurabilityServiceQosPolicy::service cleanup delay

[read]

[Not supported (optional)] Controls when the service is able to remove all

information regarding a data instances.

[default] 0

6.35.3.2 DDS HistoryQosPolicyKind DDS -

DurabilityServiceQosPolicy::history kind

The kind of history to apply in recouping durable data.

[default] DDS KEEP LAST HISTORY QOS (p. 368)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

620 Class Documentation

6.35.3.3 DDS Long DDS DurabilityServiceQosPolicy::history -

depth

Part of history QoS policy to apply when feeding a late joiner.

[default] 1

6.35.3.4 DDS Long DDS DurabilityServiceQosPolicy::max samples

Part of resource limits QoS policy to apply when feeding a late joiner.

[default] DDS LENGTH UNLIMITED (p. 371)

6.35.3.5 DDS Long DDS DurabilityServiceQosPolicy::max -

instances

Part of resource limits QoS policy to apply when feeding a late joiner.

[default] DDS LENGTH UNLIMITED (p. 371)

6.35.3.6 DDS Long DDS DurabilityServiceQosPolicy::max -

samples per instance

Part of resource limits QoS policy to apply when feeding a late joiner.

[default] DDS LENGTH UNLIMITED (p. 371)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.36 DDS Duration t Struct Reference 621

6.36 DDS Duration t Struct Reference

Type for duration representation.

Public Attributes

DDS Long sec

seconds

DDS UnsignedLong nanosec

nanoseconds

6.36.1 Detailed Description

Type for duration representation.

Represents a time interval.

Examples:

HelloWorld publisher.cxx, and HelloWorld subscriber.cxx.

6.36.2 Member Data Documentation

6.36.2.1 DDS Long DDS Duration t::sec

seconds

Examples:

HelloWorld subscriber.cxx.

6.36.2.2 DDS UnsignedLong DDS Duration t::nanosec

nanoseconds

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

622 Class Documentation

6.37 DDS DynamicData Struct Reference

A sample of any complex data type, which can be inspected and manipulated

reﬂectively.

Public Member Functions

DDS DynamicData (const DDS TypeCode ∗type, const DDS -

DynamicDataProperty t &property)

The constructor for new DDS DynamicData ( p. 622) objects.

DDS Boolean is valid () const

Indicates whether the object was constructed properly.

DDS ReturnCode t copy (const DDS DynamicData &src)

Deeply copy from the given object to this object.

DDS Boolean equal (const DDS DynamicData &other) const

Indicate whether the contents of another DDS DynamicData ( p. 622) sam-

ple are the same as those of this one.

DDS DynamicData & operator= (const DDS DynamicData

&src)

Deeply copy from the given object to this object.

DDS Boolean operator== (const DDS DynamicData &other)

const

Indicate whether the contents of another DDS DynamicData ( p. 622) sam-

ple are the same as those of this one.

DDS ReturnCode t clear all members ()

Clear the contents of all data members of this object, including key members.

DDS ReturnCode t clear nonkey members ()

Clear the contents of all data members of this object, not including key mem-

bers.

DDS ReturnCode t clear member (const char ∗member name,

DDS DynamicDataMemberId member id)

Clear the contents of a single data member of this object.

DDS ReturnCode t set buﬀer (DDS Octet ∗storage, DDS Long

size)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.37 DDS DynamicData Struct Reference 623

Associate a buﬀer with this dynamic data object.

DDS ReturnCode t get estimated max buﬀer size (DDS Long

&size)

Get the estimated maximum buﬀer size for a DynamicData object.

DDS ReturnCode t print (FILE ∗fp, int indent) const

Output a textual representation of this object and its contents to the given

ﬁle.

void get info (DDS DynamicDataInfo &info out) const

Fill in the given descriptor with information about this DDS DynamicData

( p. 622).

DDS ReturnCode t bind type (const DDS TypeCode ∗type)

If this DDS DynamicData ( p. 622) object is not yet associated with a data

type, set that type now to the given DDS TypeCode ( p. 992).

DDS ReturnCode t unbind type ()

Dissociate this DDS DynamicData ( p. 622) object from any particular

data type.

DDS ReturnCode t bind complex member (DDS -

DynamicData &value out, const char ∗member name, DDS -

DynamicDataMemberId member id)

Use another DDS DynamicData ( p. 622) object to provide access to a com-

plex ﬁeld of this DDS DynamicData ( p. 622) object.

DDS ReturnCode t unbind complex member (DDS -

DynamicData &value)

Tear down the association created by a DDS DynamicData::bind -

complex member ( p. 647) operation, committing any changes to the outer

object since then.

const DDS TypeCode ∗ get type () const

Get the data type, of which this DDS DynamicData ( p. 622) represents an

instance.

DDS TCKind get type kind () const

Get the kind of this object’s data type.

DDS UnsignedLong get member count () const

Get the number of members in this sample.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

624 Class Documentation

DDS Boolean member exists (const char ∗member name, DDS -

DynamicDataMemberId member id) const

Indicates whether a member of a particular name/ID exists in this data sam-

ple.

DDS Boolean member exists in type (const char ∗member name,

DDS DynamicDataMemberId member id) const

Indicates whether a member of a particular name/ID exists in this data sam-

ple’s type.

DDS ReturnCode t get member info (DDS -

DynamicDataMemberInfo &info, const char ∗member name,

DDS DynamicDataMemberId member id) const

Fill in the given descriptor with information about the identiﬁed member of

this DDS DynamicData ( p. 622) sample.

DDS ReturnCode t get member info by index (struct DDS -

DynamicDataMemberInfo &info, DDS UnsignedLong index)

const

Fill in the given descriptor with information about the identiﬁed member of

this DDS DynamicData ( p. 622) sample.

DDS ReturnCode t get membe r type (const DDS -

TypeCode ∗&type out, const char ∗member name, DDS -

DynamicDataMemberId member id) const

Get the type of the given member of this sample.

DDS ReturnCode t is member key (DDS Boolean &is key out,

const char ∗member name, DDS DynamicDataMemberId member -

id) const

Indicates whether a given member forms part of the key of this sample’s data

type.

DDS ReturnCode t get long (DDS Long &value out, const char

∗member name, DDS DynamicDataMemberId member id) const

Get the value of the given ﬁeld, which is of type DDS Long ( p. 300) or

another type implicitly convertible to it (DDS Octet ( p. 299), DDS Char

( p. 299), DDS Short ( p. 299), DDS UnsignedShort ( p. 299), or DDS -

Enum ( p. 301)).

DDS ReturnCode t get short (DDS Short &value out, const char

∗member name, DDS DynamicDataMemberId member id) const

Get the value of the given ﬁeld, which is of type DDS Short ( p. 299) or

another type implicitly convertible to it (DDS Octet ( p. 299) or DDS Char

( p. 299)).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.37 DDS DynamicData Struct Reference 625

DDS ReturnCode t get ulong (DDS UnsignedLong &value out,

const char ∗member name, DDS DynamicDataMemberId member -

id) c onst

Get the value of the given ﬁeld, which is of type DDS UnsignedLong

( p. 300) or another type implicitly convertible to it (DDS Octet ( p. 299),

DDS Char ( p. 299), DDS Short ( p. 299), DDS UnsignedShort

( p. 299), or DDS Enum ( p. 301)).

DDS ReturnCode t get ushort (DDS UnsignedShort &value out,

const char ∗member name, DDS DynamicDataMemberId member -

id) c onst

Get the value of the given ﬁeld, which is of type DDS UnsignedShort

( p. 299) or another type implicitly convertible to it (DDS Octet ( p. 299)

or DDS Char ( p. 299)).

DDS ReturnCode t get ﬂoat (DDS Float &value out, const char

∗member name, DDS DynamicDataMemberId member id) const

Get the value of the given ﬁeld, which is of type DDS Float ( p. 300).

DDS ReturnCode t get double (DDS Double &value out, const

char ∗member name, DDS DynamicDataMemberId member id)

const

Get the value of the given ﬁeld, which is of type DDS Double ( p. 300) or

another type implicitly convertible to it (DDS Float ( p. 300)).

DDS ReturnCode t get boolean (DDS Boolean &value out, const

char ∗member name, DDS DynamicDataMemberId member id)

const

Get the value of the given ﬁeld, which is of type DDS Boolean ( p. 301).

DDS ReturnCode t get char (DDS Char &value out, const char

∗member name, DDS DynamicDataMemberId member id) const

Get the value of the given ﬁeld, which is of type DDS Char ( p. 299).

DDS ReturnCode t get octet (DDS Octet &value out, const char

∗member name, DDS DynamicDataMemberId member id) const

Get the value of the given ﬁeld, which is of type DDS Octet ( p. 299).

DDS ReturnCode t get longlong (DDS LongLong &value out,

const char ∗member name, DDS DynamicDataMemberId member -

id) c onst

Get the value of the given ﬁeld, which is of type DDS LongLong ( p. 300) or

another type implicitly convertible to it (DDS Octet ( p. 299), DDS Char

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

626 Class Documentation

( p. 299), DDS Short ( p. 299), DDS UnsignedShort ( p. 299), DDS -

Long ( p. 300), DDS UnsignedLong ( p. 300), or DDS Enum ( p. 301)).

DDS ReturnCode t get ulonglong (DDS UnsignedLongLong

&value out, const char ∗me mber name, DDS -

DynamicDataMemberId member id) const

Get the value of the given ﬁeld, which is of type DDS UnsignedLongLong

( p. 300) or another type implicitly convertible to it (DDS Octet ( p. 299),

DDS Char ( p. 299), DDS Short ( p. 299), DDS UnsignedShort

( p. 299), DDS Long ( p. 300), DDS UnsignedLong ( p. 300), or DDS -

Enum ( p. 301)).

DDS ReturnCode t get longdouble (DDS LongDouble &value -

out, const char ∗member name, DDS DynamicDataMemberId mem-

ber id) const

Get the value of the given ﬁeld, which is of type DDS LongDouble ( p. 300)

or another ty pe implicitly convertible to it (DDS Float ( p. 300) or DDS -

Double ( p. 300)).

DDS ReturnCode t get wchar (DDS Wchar &value out, const char

∗member name, DDS DynamicDataMemberId member id) const

Get the value of the given ﬁeld, which is of type DDS Wchar ( p. 299) or

another type implicitly convertible to it (DDS Char ( p. 299)).

DDS ReturnCode t get string (char ∗&value, DDS UnsignedLong

∗size, const char ∗member name, DDS DynamicDataMemberId

member id) const

Get the value of the given ﬁeld, which is of type char∗.

DDS ReturnCode t get wstring (DDS Wchar ∗&value,

DDS UnsignedLong ∗size, const char ∗member name, DDS -

DynamicDataMemberId member id) const

Get the value of the given ﬁeld, which is of type DDS Wchar ( p. 299)∗.

DDS ReturnCode t get complex member (DDS -

DynamicData &value out, const char ∗member name, DDS -

DynamicDataMemberId member id) const

Get a copy of the value of the given ﬁeld, which is of some composed type.

DDS ReturnCode t get long array (DDS Long ∗array, DDS -

UnsignedLong ∗length, const char ∗member name, DDS -

DynamicDataMemberId member id) const

Get a copy of the given array member.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.37 DDS DynamicData Struct Reference 627

DDS ReturnCode t get short array (DDS Short ∗array,

DDS UnsignedLong ∗length, const char ∗member name, DDS -

DynamicDataMemberId member id) const

Get a copy of the given array member.

DDS ReturnCode t get ulong array (DDS UnsignedLong ∗array,

DDS UnsignedLong ∗length, const char ∗member name, DDS -

DynamicDataMemberId member id) const

Get a copy of the given array member.

DDS ReturnCode t get ushort array (DDS UnsignedShort

∗array, DDS UnsignedLong ∗length, const char ∗member name,

DDS DynamicDataMemberId member id) const

Get a copy of the given array member.

DDS ReturnCode t get ﬂoat array (DDS Float ∗array, DDS -

UnsignedLong ∗length, const char ∗member name, DDS -

DynamicDataMemberId member id) const

Get a copy of the given array member.

DDS ReturnCode t get double array (DDS Double ∗array,

DDS UnsignedLong ∗length, const char ∗member name, DDS -

DynamicDataMemberId member id) const

Get a copy of the given array member.

DDS ReturnCode t get boolean array (DDS Boolean ∗array,

DDS UnsignedLong ∗length, const char ∗member name, DDS -

DynamicDataMemberId member id) const

Get a copy of the given array member.

DDS ReturnCode t get char array (DDS Char ∗array, DDS -

UnsignedLong ∗length, const char ∗member name, DDS -

DynamicDataMemberId member id) const

Get a copy of the given array member.

DDS ReturnCode t get octet array (DDS Octet ∗array,

DDS UnsignedLong ∗length, const char ∗member name, DDS -

DynamicDataMemberId member id) const

Get a copy of the given array member.

DDS ReturnCode t get longlong array (DDS LongLong ∗array,

DDS UnsignedLong ∗length, const char ∗member name, DDS -

DynamicDataMemberId member id) const

Get a copy of the given array member.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

628 Class Documentation

DDS ReturnCode t get ulonglong array (DDS -

UnsignedLongLong ∗array, DDS UnsignedLong ∗length, const

char ∗member name, DDS DynamicDataMemberId member id)

const

Get a copy of the given array member.

DDS ReturnCode t get longdouble array (DDS LongDouble

∗array, DDS UnsignedLong ∗length, const char ∗member name,

DDS DynamicDataMemberId member id) const

Get a copy of the given array member.

DDS ReturnCode t get wchar array (DDS Wchar ∗array,

DDS UnsignedLong ∗length, const char ∗member name, DDS -

DynamicDataMemberId member id) const

Get a copy of the given array member.

DDS ReturnCode t get long seq (DDS LongSeq &seq, const char

∗member name, DDS DynamicDataMemberId member id) const

Get a copy of the given sequence member.

DDS ReturnCode t get short seq (DDS ShortSeq &se q, const char

∗member name, DDS DynamicDataMemberId member id) const

Get a copy of the given sequence member.

DDS ReturnCode t get ulong seq (DDS UnsignedLongSeq &seq,

const char ∗member name, DDS DynamicDataMemberId member -

id) const

Get a copy of the given sequence member.

DDS ReturnCode t get ushort seq (DDS UnsignedShortSeq

&seq, const char ∗member name, DDS DynamicDataMemberId

member id) const

Get a copy of the given sequence member.

DDS ReturnCode t get ﬂoat seq (DDS FloatSeq &seq, const char

∗member name, DDS DynamicDataMemberId member id) const

Get a copy of the given sequence member.

DDS ReturnCode t get double seq (DDS DoubleSeq &seq, const

char ∗member name, DDS DynamicDataMemberId member id)

const

Get a copy of the given sequence member.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.37 DDS DynamicData Struct Reference 629

DDS ReturnCode t get boolean seq (DDS BooleanSeq &seq,

const char ∗member name, DDS DynamicDataMemberId member -

id) c onst

Get a copy of the given sequence member.

DDS ReturnCode t get char seq (DDS CharSeq &seq, const char

∗member name, DDS DynamicDataMemberId member id) const

Get a copy of the given sequence member.

DDS ReturnCode t get octet seq (DDS OctetSeq &se q, const char

∗member name, DDS DynamicDataMemberId member id) const

Get a copy of the given sequence member.

DDS ReturnCode t get longlong seq (DDS LongLongSeq &seq,

const char ∗member name, DDS DynamicDataMemberId member -

id) c onst

Get a copy of the given sequence member.

DDS ReturnCode t get ulonglong seq (DDS -

UnsignedLongLongSeq &seq, const char ∗member name, DDS -

DynamicDataMemberId member id) const

Get a copy of the given sequence member.

DDS ReturnCode t get longdouble seq (DDS LongDoubleSeq

&seq, const char ∗member name, DDS DynamicDataMemberId

member id) const

Get a copy of the given sequence member.

DDS ReturnCode t get wchar seq (DDS WcharSeq &seq, const

char ∗member name, DDS DynamicDataMemberId member id)

const

Get a copy of the given sequence member.

DDS ReturnCode t set long (const char ∗member name, DDS -

DynamicDataMemberId member id, DDS Long value)

Set the value of the given ﬁeld, which is of type DDS Long ( p. 300).

DDS ReturnCode t set short (const char ∗member name, DDS -

DynamicDataMemberId member id, DDS Short value)

Set the value of the given ﬁeld, which is of type DDS Short ( p. 299).

DDS ReturnCode t set ulong (const char ∗member name, DDS -

DynamicDataMemberId member id, DDS UnsignedLong value)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

630 Class Documentation

Set the value of the given ﬁeld, which is of type DDS UnsignedLong

( p. 300).

DDS ReturnCode t set ushort (const char ∗member name, DDS -

DynamicDataMemberId member id, DDS UnsignedShort value)

Set the value of the given ﬁeld, which is of type DDS UnsignedShort

( p. 299).

DDS ReturnCode t set ﬂoat (const char ∗member name, DDS -

DynamicDataMemberId member id, DDS Float value)

Set the value of the given ﬁeld, which is of type DDS Float ( p. 300).

DDS ReturnCode t set double (const char ∗member name, DDS -

DynamicDataMemberId member id, DDS Double value)

Set the value of the given ﬁeld, which is of type DDS Double ( p. 300).

DDS ReturnCode t set boolean (const char ∗member name, DDS -

DynamicDataMemberId member id, DDS Boolean value)

Set the value of the given ﬁeld, which is of type DDS Boolean ( p. 301).

DDS ReturnCode t set char (const char ∗member name, DDS -

DynamicDataMemberId member id, DDS Char value)

Set the value of the given ﬁeld, which is of type DDS Char ( p. 299).

DDS ReturnCode t set octet (const char ∗member name, DDS -

DynamicDataMemberId member id, DDS Octet value)

Set the value of the given ﬁeld, which is of type DDS Octet ( p. 299).

DDS ReturnCode t set longlong (const char ∗member name, DDS -

DynamicDataMemberId member id, DDS LongLong value)

Set the value of the given ﬁeld, which is of type DDS LongLong ( p. 300).

DDS ReturnCode t set ulonglong (const char ∗member -

name, DDS DynamicDataMemberId member id, DDS -

UnsignedLongLong value)

Set the value of the given ﬁeld, which is of type DDS UnsignedLongLong

( p. 300).

DDS ReturnCode t set longdouble (const char ∗member name,

DDS DynamicDataMemberId member id, DDS LongDouble

value)

Set the value of the given ﬁeld, which is of type DDS LongDouble ( p. 300).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.37 DDS DynamicData Struct Reference 631

DDS ReturnCode t set wchar (const char ∗member name, DDS -

DynamicDataMemberId member id, DDS Wchar value)

Set the value of the given ﬁeld, which is of type DDS Wchar ( p. 299).

DDS ReturnCode t set string (const char ∗member name, DDS -

DynamicDataMemberId member id, const char ∗value)

Set the value of the given ﬁeld of type char∗.

DDS ReturnCode t set wstring (const char ∗member name, DDS -

DynamicDataMemberId member id, const DDS Wchar ∗value)

Set the value of the given ﬁeld of type DDS Wcha r ( p. 299)∗.

DDS ReturnCode t set complex member (const char ∗member -

name, DDS DynamicDataMemberId member id, const DDS -

DynamicData &value)

Copy the state of the given DDS DynamicData ( p. 622) object into a mem-

ber of this object.

DDS ReturnCode t set long array (const char ∗member name,

DDS DynamicDataMemberId member id, DDS UnsignedLong

length, c onst DDS Long ∗array)

Set the contents of the given array member.

DDS ReturnCode t set short array (const char ∗member name,

DDS DynamicDataMemberId member id, DDS UnsignedLong

length, c onst DDS Short ∗array)

Set the contents of the given array member.

DDS ReturnCode t set ulong array (const char ∗member name,

DDS DynamicDataMemberId member id, DDS UnsignedLong

length, c onst DDS UnsignedLong ∗array)

Set the contents of the given array member.

DDS ReturnCode t set ushort array (const char ∗member name,

DDS DynamicDataMemberId member id, DDS UnsignedLong

length, c onst DDS UnsignedShort ∗array)

Set the contents of the given array member.

DDS ReturnCode t set ﬂoat array (const char ∗member name,

DDS DynamicDataMemberId member id, DDS UnsignedLong

length, c onst DDS Float ∗array)

Set the contents of the given array member.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

632 Class Documentation

DDS ReturnCode t set double array (const char ∗member name,

DDS DynamicDataMemberId member id, DDS UnsignedLong

length, c onst DDS Double ∗array)

Set the contents of the given array member.

DDS ReturnCode t set boolean array (const char ∗member name,

DDS DynamicDataMemberId member id, DDS UnsignedLong

length, c onst DDS Boolean ∗array)

Set the contents of the given array member.

DDS ReturnCode t set char array (const char ∗member name,

DDS DynamicDataMemberId member id, DDS UnsignedLong

length, c onst DDS Char ∗array)

Set the contents of the given array member.

DDS ReturnCode t set octet array (const char ∗member name,

DDS DynamicDataMemberId member id, DDS UnsignedLong

length, c onst DDS Octet ∗array)

Set the contents of the given array member.

DDS ReturnCode t set longlong array (const char ∗member name,

DDS DynamicDataMemberId member id, DDS UnsignedLong

length, c onst DDS LongLong ∗array)

Set the contents of the given array member.

DDS ReturnCode t set ulonglong array (const char ∗member -

name, DDS DynamicDataMemberId member id, DDS -

UnsignedLong length, const DDS UnsignedLongLong ∗array)

Set the contents of the given array member.

DDS ReturnCode t set longdouble array (const char ∗member -

name, DDS DynamicDataMemberId member id, DDS -

UnsignedLong length, const DDS LongDouble ∗array)

Set the contents of the given array member.

DDS ReturnCode t set wchar array (const char ∗member name,

DDS DynamicDataMemberId member id, DDS UnsignedLong

length, c onst DDS Wchar ∗array)

Set the contents of the given array member.

DDS ReturnCode t set long seq (const char ∗member name, DDS -

DynamicDataMemberId member id, const DDS LongSeq &value)

Set the contents of the given sequence member.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.37 DDS DynamicData Struct Reference 633

DDS ReturnCode t set short seq (const char ∗member name,

DDS DynamicDataMemberId member id, const DDS ShortSeq

&value)

Set the contents of the given sequence member.

DDS ReturnCode t set ulong seq (const char ∗member -

name, DDS DynamicDataMemberId member id, const DDS -

UnsignedLongSeq &value)

Set the contents of the given sequence member.

DDS ReturnCode t set ushort seq (const char ∗member -

name, DDS DynamicDataMemberId member id, const DDS -

UnsignedShortSeq &value)

Set the contents of the given sequence member.

DDS ReturnCode t set ﬂoat seq (const char ∗member name, DDS -

DynamicDataMemberId member id, const DDS FloatSeq &value)

Set the contents of the given sequence member.

DDS ReturnCode t set double seq (const char ∗member name,

DDS DynamicDataMemberId member id, const DDS DoubleSeq

&value)

Set the contents of the given sequence member.

DDS ReturnCode t set boolean seq (const char ∗member name,

DDS DynamicDataMemberId member id, const DDS BooleanSeq

&value)

Set the contents of the given sequence member.

DDS ReturnCode t set char seq (const char ∗member name, DDS -

DynamicDataMemberId member id, const DDS CharSeq &value)

Set the contents of the given sequence member.

DDS ReturnCode t set octet seq (const char ∗member name,

DDS DynamicDataMemberId member id, const DDS OctetSeq

&value)

Set the contents of the given sequence member.

DDS ReturnCode t set longlong seq (const char ∗member -

name, DDS DynamicDataMemberId member id, const DDS -

LongLongSeq &value)

Set the contents of the given sequence member.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

634 Class Documentation

DDS ReturnCode t set ulonglong seq (const char ∗member -

name, DDS DynamicDataMemberId member id, const DDS -

UnsignedLongLongSeq &value)

Set the contents of the given sequence member.

DDS ReturnCode t set longdouble seq (const char ∗member -

name, DDS DynamicDataMemberId member id, const DDS -

LongDoubleSeq &value)

Set the contents of the given sequence member.

DDS ReturnCode t set wchar seq (const char ∗member name,

DDS DynamicDataMemberId member id, const DDS WcharSeq

&value)

Set the contents of the given sequence member.

6.37.1 Detailed Description

A sample of any complex data type, which can be inspected and manipulated

reﬂectively.

Objects of type DDS Dynamic Data (p. 622) represent corresponding objects

of the type identiﬁed by their DDS TypeCode (p. 992). Because the deﬁnition

of these types may not have existed at compile time on the system on which the

application is running, you will interact with the data using an API of reﬂective

getters and setters.

For example, if you had access to your data types at compile time, you could

do this:

theValue = theObject.theField;

Instead, you will do something like this:

theValue = get(theObject, "theField");

DDS DynamicData (p. 622) objects can represent any complex data

type, including those of type kinds DDS TK ARRAY (p. 66), DDS -

TK SEQUENCE (p. 66), DDS TK STRUCT (p. 66), DDS TK UNION

(p. 66), DDS TK VALUE (p. 67), and DDS TK SPARSE (p. 67). They

cannot represent objects of basic types (e.g. integers and strings). Since those

type deﬁnitions always exist on every system, you can examine their objects

directly.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.37 DDS DynamicData Struct Reference 635

6.37.2 Member Names and IDs

The members of a data type can be identiﬁed in one of two ways: by their name

or by their numeric ID. The former is often more transparent to human users;

the latter is typically faster.

You deﬁne the name and ID of a type member when you add that member

to that type. When you deﬁne a sparse type, you will typically choose both

explicitly. If you deﬁne your type in IDL or XML, the name will be the ﬁeld

name that appears in the type deﬁnition; the ID will be the one-based index of

the ﬁeld in declaration order. For example, in the following IDL structure, the

ID of theLong is 2.

struct MyType {

short theShort;

long theLong;

};

For unions (DDS TK UNION (p. 66)), the ID of a member is the discrimi-

nator value corresponding to that member.

6.37.3 Arrays and Sequences

The ”members” of array and sequence types, unlike those of structure and

union types, don’t have names or explicit member IDs. However, they may

nevertheless be accessed by ”ID”: the ID is one more than the index. (The ﬁrst

element has ID 1, the second 2, etc.)

Multi-dimensional arrays are eﬀectively ﬂattened by this pattern. For example,

for an array theArray[4][5], accessing ID 7 is equivalent to index 6, or the s ec ond

element of the second group of 5.

To determine the length of a collection-typed member of a structure or union,

you have two choices:

1. Get the length along with the data: call the appropriate array accessor

(see Getters and Setters (p. 637)) and check the resulting length.

2. Get the length without getting the data itself: call DDS -

DynamicData::get member info (p. 652) and check the resulting

DDS DynamicDataMemberInfo::element count (p. 723).

6.37.4 Available Functionality

The Dynamic Data API is large when measured by the number of methods it

contains. But each method falls into one of a very small number of categories.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

636 Class Documentation

You will ﬁnd it easier to navigate this documentation if you understand these

categories.

6.37.4.1 Lifecycle and Utility Methods

Managing the lifecycle of DDS DynamicData (p. 622) objects is simple. You

have two choices:

1. Usually, you will go through a DDSDynamicDataTypeSupport

(p. 1246) factory object, which will ensure that the type and property in-

formation for the new DDS DynamicData (p. 622) object corresponds

to a registered type in your system.

2. In certain advanced cases, such as when you’re navigating a neste d struc-

ture, you will want to have a DDS DynamicData (p. 622) object that

is not bound up front to any particular type, or you will want to initialize

the object in a custom way. In that case, you can call the constructor

directly.

DDSDynamicDataTypeSupport

(p. 1246)

DDS DynamicData (p. 622)

DDSDynamicDataTypeSup-

port::create data

(p. 1250)

DDS DynamicData::DDS -

DynamicData

DDSDynamicDataTypeSup-

port::delete data

(p. 1251)

DDS DynamicData::∼DDS -

DynamicData

Table 6.1: Lifecycle

You can also copy DDS DynamicData (p. 622) objects:

DDS DynamicData::copy (p. 641)

DDS DynamicData::operator= (p. 642)

You can test them for equality:

DDS DynamicData::equal (p. 641)

DDS DynamicData::operator== (p. 642)

And you can print their contents:

DDS DynamicData::print (p. 645)

DDSDynamicDataTypeSupport::print data (p. 1251)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.37 DDS DynamicData Struct Reference 637

6.37.4.2 Getters and Setters

Most methods get or set the value of some ﬁeld. These methods are named

according to the type of the ﬁeld they access.

The names of integer types vary across languages. The programming API for

each language reﬂects that programming language. However, if your chosen lan-

guage does not use the same names as the language that you used to deﬁne your

types (e.g., IDL), or if you need to interoperate among programming languages,

you will need to understand these diﬀerences. They are explained the following

table.

Type IDL C, C++ C# Java

16-bit

integer

short DDS Short short short

32-bit

integer

long DDS Long int int

64-bit

integer

long long DDS -

LongLong

long long

Table 6.2: Integer Type Names Across Languages

When working with a DDS DynamicData (p. 622) object representing an

array or sequence, calling one of the ”get” methods below for an index that is

out of bounds will result in DDS RETCODE NO DATA (p. 316). Calling

”set” for an index that is past the end of a sequence will cause that sequence to

automatically le ngthen (ﬁlling w ith default contents).

In addition to getting or setting a ﬁeld, you can ”clear” its value; that is, set it

to a default zero value.

DDS DynamicData::clear member (p. 643)

DDS DynamicData::clear all members (p. 642)

DDS DynamicData::clear nonkey members (p. 643)

6.37.4.3 Query and Iteration

Not all components of your application will have static knowledge of all of the

ﬁelds of your type. Sometimes, you will want to query meta-data about the

ﬁelds that appear in a given data sample.

DDS DynamicData::get type (p. 650)

DDS DynamicData::get type kind (p. 650)

DDS DynamicData::get member type (p. 654)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

638 Class Documentation

DDS DynamicData::get member info (p. 652)

DDS DynamicData::get member count (p. 650)

DDS DynamicData::get member info by index (p. 653)

DDS DynamicData::member exists (p. 651)

DDS DynamicData::member exists in type (p. 652)

DDS DynamicData::is member key (p. 654)

6.37.4.4 Type/Object Association

Sometimes, you may want to change the association between a data object and

its type. This is not something you can do with a typical object, but with

DDS DynamicData (p. 622) objects, it is a powerful capability. It allows

you to, for example, examine nested structures without copying them by using

a ”bound” DDS DynamicData (p. 622) object as a view into an enclosing

DDS DynamicData (p. 622) object.

DDS DynamicData::bind type (p. 646)

DDS DynamicData::unbind type (p. 647)

DDS DynamicData::bind complex member (p. 647)

DDS DynamicData::unbind complex member (p. 649)

6.37.4.5 Keys

Keys can be speciﬁed in dynamically deﬁned types just as they can in types

deﬁned in generated code. However, there are some minor restrictions when

sparse value types are involved (see DDS TK SPARSE (p. 67)).

If a type has a member that is of a sparse value type, that member cannot

be a key for the enclosing type.

Sparse value types themselves may have at most a single key ﬁeld. T hat

ﬁeld may itself be of any type.

6.37.5 Performance

Due to the way in which DDS DynamicData (p. 622) objects manage their

internal state, it is typically more eﬃcient, when setting the ﬁeld values of a

DDS DynamicData (p. 622) for the ﬁrst time, to do so in the declared order

of those ﬁelds.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.37 DDS DynamicData Struct Reference 639

For example, suppose a type deﬁnition like the following:

struct MyType {

float my_float;

sequence<octet> my_bytes;

short my_short;

};

The richness of the type system makes it diﬃcult to fully characterize the per-

formance diﬀerences between all access patterns. Nevertheless, the following are

generally true:

It will be most performant to set the value of my float, then my bytes,

and ﬁnally my short.

The order of modiﬁcation has a greater impact for types of kind DDS -

TK STRUCT (p. 66) and DDS TK VALUE (p. 67) than it does for

types of kind DDS TK SPARSE (p. 67).

Modiﬁcations to variable-sized types (i.e. those containing strings, se-

quences, unions, or optional members) are more expensive than modiﬁca-

tions to ﬁxed-size types.

MT Safety:

UNSAFE. In general, using a single DDS DynamicData (p. 622) object

concurrently from multiple threads is unsafe.

6.37.6 Constructor & Destructor Documentation

6.37.6.1 DDS DynamicData::DDS DynamicData (const DDS -

TypeCode ∗ type, const DDS DynamicDataProperty t &

property)

The constructor for new DDS DynamicData (p. 622) objects.

The type parameter may be NULL. In that case, this DDS DynamicData

(p. 622) must be bound with DDS DynamicDat a::bi nd type (p. 646) or

DDS DynamicData::bind complex member (p. 647) before it can be used.

If the DDS TypeCode (p. 992) is not NULL, the newly constructed DDS -

DynamicData (p. 622) object will retain a reference to it. It is not safe to

delete the DDS TypeCode (p. 992) until all samples that use it have them-

selves been deleted.

In most cases, it is not necessary to call this constructor explicitly. Instead, use

DDSDynamicDataTypeSupport::create data (p. 1250), and the DDS -

TypeCode (p. 992) and properties will be speciﬁed for you. Using the factory

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

640 Class Documentation

method also ensures that the memory management contract documented above

is followed correctly, because the DDSDynamicDataTypeSupport (p. 1246)

object maintains the DDS TypeCode (p. 992) used by the samples it creates.

However you create a DDS DynamicData (p. 622) object, you must delete it

when you are ﬁnished with it. If you choose to use this constructor, delete the

object with the destructor: DDS DynamicData::∼DDS DynamicData.

DDS_DynamicData* sample = new DDS_DynamicData(

myType, myProperties);

// Failure indicated by i s_va lid( ) method.

// Do something...

delete sample;

NOTE that RTI Connext does not explicitly generate any exceptions in

this constructor, because C++ exception support is not consistent across all

platforms on which RTI Connext runs. Therefore, to check whether con-

struction succeeded, you must use the DDS DynamicData::is valid (p. 640)

method. Alternatively, you can create an DDS DynamicData (p. 622) object

with DDSDynamicDataTypeSupport::create data (p. 1250), which re-

turns NULL on failure, eliminating the need to call DDS DynamicData::is -

valid (p. 640).

Parameters:

type <<in>> ( p. 200) The type of which the new object will represent

an object.

property <<in>> ( p. 200) Properties that conﬁgure the behavior of the

new object. Most users can simply use DDS DYNAMIC DATA -

PROPERTY DEFAULT (p. 80).

See also:

DDS DynamicData::is valid (p. 640)

DDS DynamicData::∼DDS DynamicData

DDSDynamicDataTypeSupport::create data (p. 1250)

6.37.7 Member Function Documentation

6.37.7.1 DDS Boolean DDS DynamicData::is valid () const

Indicates whether the object was constructed properly.

This method returns DDS BOOLEAN TRUE (p. 298) if the constructor suc-

ceeded; it returns DDS BOOLEAN FALSE (p. 299) if the constructor failed

for any reason, which should also have resulted in a log message. It is only

necessary to call this method if you created the DDS DynamicData (p. 622)

object using the constructor, DDS DynamicData::DDS DynamicData.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.37 DDS DynamicData Struct Reference 641

Possible failure reasons include passing an invalid type or invalid properties to

the constructor.

This method is necessary because C++ exception support is not c onsistent

across all of the platforms on which RTI Connext runs. Therefore, the imple-

mentation does not throw any exceptions in the constructor.

MT Safety:

UNSAFE.

See also:

DDS DynamicData::DDS DynamicData

6.37.7.2 DDS ReturnCode t DDS DynamicData::copy (const

DDS DynamicData & src)

Deeply copy from the given object to this object.

MT Safety:

UNSAFE.

Returns:

One of the Standard Return Codes (p. 314) or DDS RETCODE -

OUT OF RESOURCES (p. 315)

See also:

DDS DynamicData::operator= (p. 642)

6.37.7.3 DDS Boolean DDS DynamicData::equal (const

DDS DynamicData & other) const

Indicate whether the contents of another DDS DynamicData (p. 622) sample

are the same as those of this one.

This operation compares the data and type of existing members. The types of

non-instantiated members may diﬀer in sparse types.

MT Safety:

UNSAFE.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

642 Class Documentation

See also:

DDS DynamicData::operator== (p. 642)

DDS TK SPARSE (p. 67)

6.37.7.4 DDS DynamicData& DDS DynamicData::operator=

(const DDS DynamicData & src)

Deeply copy from the given object to this object.

MT Safety:

UNSAFE.

See also:

DDS DynamicData::copy (p. 641)

6.37.7.5 DDS Boolean DDS DynamicData::operator== (const

DDS DynamicData & other) const

Indicate whether the contents of another DDS DynamicData (p. 622) sample

are the same as those of this one.

This operation compares the data and type of existing members. The types of

non-instantiated members may diﬀer in sparse types.

MT Safety:

UNSAFE.

See also:

DDS DynamicData::equal (p. 641)

DDS TK SPARSE (p. 67)

6.37.7.6 DDS ReturnCode t DDS DynamicData::clear all members

()

Clear the contents of all data members of this object, including key members.

MT Safety:

UNSAFE.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.37 DDS DynamicData Struct Reference 643

Returns:

One of the Standard Return Codes (p. 314)

See also:

DDS DynamicData::clear nonkey members (p. 643)

DDS DynamicData::clear member (p. 643)

6.37.7.7 DDS ReturnCode t DDS DynamicData::clear nonkey -

members ()

Clear the contents of all data members of this object, not including key members.

This method is only applicable to sparse value types.

MT Safety:

UNSAFE.

Returns:

One of the Standard Return Codes (p. 314)

See also:

DDS TK SPARSE (p. 67)

DDS DynamicData::clear all members (p. 642)

DDS DynamicData::clear member (p. 643)

6.37.7.8 DDS ReturnCode t DDS DynamicData::clear -

member (const char ∗ member name,

DDS DynamicDataMemberId member id)

Clear the contents of a single data member of this object.

This method is only applicable to sparse value types.

MT Safety:

UNSAFE.

Parameters:

member name <<in>> ( p. 200) The name of the member or NULL to

look up the member by its ID.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

644 Class Documentation

member id <<in>> ( p. 200) The ID of the member or DDS -

DYNAMIC DATA MEMBER ID UNSPECIFIED (p. 80) to

look up by name. See Member Names and IDs (p. 635).

Returns:

One of the Standard Return Codes (p. 314)

See also:

DDS TK SPARSE (p. 67)

DDS DynamicData::clear all members (p. 642)

DDS DynamicData::clear nonkey members (p. 643)

6.37.7.9 DDS ReturnCode t DDS DynamicData::set buﬀer

(DDS Octet ∗ storage, DDS Long size)

Associate a buﬀer with this dynamic data object.

The DynamicData object will use the input buﬀer to store its value.

If the DynamicData object already has a value, this function will clear the

contents of all data members.

The memory of the buﬀer being replaced will be freed, unless the buﬀer was

assigned by a previous call to this method.

If the size of the input buﬀer is not big enough to hold the future value of

the DynamicData object, the set operations will return DDS RETCODE -

OUT OF RESOURCES (p. 315) when the size is exceeded.

The internal representation of a DynamicData object is based on CDR encap-

sulation and introduces additional overhead beyond the data representation of

the equivalent C structure. When providing an input buﬀer, try to account for

that overhead.

The method DDS DynamicData::get estimated max buﬀer size (p. 645)

can be used to obtain an estimated maximum size for the input buﬀer. This size

is calculated based on an assignment pattern where the value of a data member

is set a single time between calls to DDS DynamicData::clear all memb ers

(p. 642).

MT Safety:

UNSAFE.

Parameters:

storage <<in>> ( p. 200) Storage buﬀer.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.37 DDS DynamicData Struct Reference 645

size <<in>> ( p. 200) Buﬀer size in bytes.

Returns:

One of the Standard Return Codes (p. 314)

6.37.7.10 DDS ReturnCode t DDS DynamicData::get -

estimated max buﬀer size (DDS Long &

size)

Get the estimated maximum buﬀer size for a DynamicData object.

This method gets the estimated maximum buﬀer size of a DynamicData object

based on the associated type.

The output size is calculated based on an ass ignment pattern where the

value of a data member is set a single time between calls to DDS -

DynamicData::clear all members (p. 642).

If this is not the case (for example, the value of a string member is set multiple

times), the maximum size returned by this method may not be representative.

This method can be used to obtain the size of the buﬀer provided to the method

DDS DynamicData::set buﬀer (p. 644).

MT Safety:

UNSAFE.

Parameters:

size <<out>> ( p. 200) Estimated maximum buﬀer size in bytes.

Returns:

One of the Standard Return Codes (p. 314)

6.37.7.11 DDS ReturnCode t DDS DynamicData::print (FILE ∗

fp, int indent) const

Output a te xtual representation of this object and its contents to the given ﬁle.

This method is equivalent to DDSDynamicDataTypeSupport::print data

(p. 1251).

Warning: This operation may not display any data for members at the end

of a data structure that have not been explicitly set before the data sample is

serialized. This will not be a problem on a received data sample, which should

always correctly display all members.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

646 Class Documentation

MT Safety:

UNSAFE.

Parameters:

fp <<in>> ( p. 200) The ﬁle to which the object should be printed.

indent <<in>> ( p. 200) The output of this method will be pretty-

printed. This argument indicates the amount of initial indentation

of the output.

Returns:

One of the Standard Return Codes (p. 314)

See also:

DDSDynamicDataTypeSupport::print data (p. 1251)

6.37.7.12 void DDS DynamicDat a::get info

(DDS DynamicDataInfo & info out) const

Fill in the given descriptor with information about this DDS DynamicData

(p. 622).

MT Safety:

UNSAFE.

Parameters:

info out <<out>> ( p. 200) The descriptor object whose contents will be

overwritten by this operation.

6.37.7.13 DDS ReturnCode t DDS DynamicData::bind type (const

DDS TypeCode ∗ type)

If this DDS DynamicData (p. 622) objec t is not yet associated with a data

type, set that type now to the given DDS TypeCode (p. 992).

This advanced ope ration allows you to reuse a single DDS DynamicData

(p. 622) object with multiple data types.

DDS_DynamicData* myData = new DDS_DynamicData(NULL, myProperties);

DDS_TypeCode* myType = ...;

myData->bind_type(myType);

// Do something...

myData->unbind_type();

delete myData;

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.37 DDS DynamicData Struct Reference 647

Note that the DDS DynamicData (p. 622) object will retain a reference to

the DDS TypeCode (p. 992) object you provide. It is not safe to delete the

DDS TypeCode (p. 992) until after it is unbound.

MT Safety:

UNSAFE.

Parameters:

type <<in>> ( p. 200) The type to associate with this DDS -

DynamicData (p. 622) object.

Returns:

One of the Standard Return Codes (p. 314)

See also:

DDS DynamicData::unbind type (p. 647)

6.37.7.14 DDS ReturnCode t DDS DynamicData::unbind type ()

Dissociate this DDS DynamicData (p. 622) object from any particular data

type.

This step is nece ss ary before the object can be associated with a new data type.

This operation clears all members as a side eﬀect.

MT Safety:

UNSAFE.

Returns:

One of the Standard Return Codes (p. 314)

See also:

DDS DynamicData::bind type (p. 646)

DDS DynamicData::clear all members (p. 642)

6.37.7.15 DDS ReturnCode t DDS DynamicData::bind complex -

member (DDS DynamicData & value out, const

char ∗ member name, DDS DynamicDataMemberId

member id)

Use another DDS DynamicData (p. 622) object to provide access to a com-

plex ﬁeld of this DDS DynamicData (p. 622) object.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

648 Class Documentation

For example, consider the following data types:

struct MyFieldType {

float theFloat;

};

struct MyOuterType {

MyFieldType complexMember;

};

Supp ose you have an instance of MyOuterType, and you would like to examine

the contents of its member complexMember. To do this, you must bind another

DDS DynamicData (p. 622) object to that member. This operation w ill bind

the type code of the member to the provided DDS DynamicData (p. 622)

object and perform additional initialization.

The following example demonstrates the usage pattern. Note that error handling

has been omitted for brevity.

DDS_DynamicData outer = ...;

DDS_DynamicData toBeBound(NULL, myProperties);

outer.bind_complex_member(

toBeBound,

"complexMember",

DDS_DYNAMIC_DATA_MEMBER_ID_UNSPECIFIED);

float theFloatValue = 0.0f;

toBeBound.get_float(

theFloat,

"theFloat"

DDS_DYNAMIC_DATA_MEMBER_ID_UNSPECIFIED);

outer.unbind_complex_member(toBeBound);

This operation is only permitted w hen the object toBeBound (named as in the

example above) is not currently associated with any type, including already

being bound to another member. You can see in the example that this object

is created directly with the constructer and is not provided with a DDS -

TypeCode (p. 992).

Only a single member of a given DDS DynamicData (p. 622) object may

be bound at one time – however, members of members may be recursively

bound to any depth. Furthermore, while the outer object has a bound member,

it may only be modiﬁed through that bound member. That is, after calling

this member, all ”set” operations on the outer object will be disabled until

DDS DynamicData::unbind complex member (p. 649) has been called.

Furthermore, any bound member must be unbound before a sample can be

written or deleted.

This method is logically related to DDS DynamicData::get complex -

member (p. 666) in that both allow you to examine the state of nested objec ts.

They are diﬀerent in an important way: this method provides a view into an

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.37 DDS DynamicData Struct Reference 649

outer object, such that any change made to the inner object will be reﬂected

in the outer. But the DDS DynamicData::get complex member (p. 666)

operation copies the state of the nested object; changes to it will not be reﬂected

in the source object.

Note that you can bind to a member of a sequence at an index that is past the

current length of that sequence. In that case, this method behaves like a ”set”

method: it automatically lengthens the sequence (ﬁlling in default elements) to

allow the bind to take place. See Getters and Setters (p. 637).

MT Safety:

UNSAFE.

Parameters:

value out <<out>> ( p. 200) The object that you wish to bind to the

ﬁeld.

member name <<in>> ( p. 200) The name of the member or NULL to

look up the member by its ID.

member id <<in>> ( p. 200) The ID of the member or DDS -

DYNAMIC DATA MEMBER ID UNSPECIFIED (p. 80) to

look up by name. See Member Names and IDs (p. 635).

Returns:

One of the Standard Return Codes (p. 314)

See also:

DDS DynamicData::unbind complex member (p. 649)

DDS DynamicData::get complex member (p. 666)

6.37.7.16 DDS ReturnCode t DDS DynamicData::unbind -

complex member (DDS DynamicData &

value)

Tear down the association c reated by a DDS DynamicData::bind -

complex member (p. 647) operation, committing any changes to the outer

object since then.

Some changes to the outer object will not be observable until after you have

performed this operation.

If you have called DDS DynamicData::bind complex member (p. 647) on

a data sample, you must unbind before writing or deleting the sample.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

650 Class Documentation

MT Safety:

UNSAFE.

Parameters:

value <<in>> ( p. 200) The same object you passed to DDS -

DynamicData::bind complex member (p. 647). This argument

is used for error checking purposes.

Returns:

One of the Standard Return Codes (p. 314) or DDS RETCODE -

OUT OF RESOURCES (p. 315)

See also:

DDS DynamicData::bind complex member (p. 647)

6.37.7.17 const DDS TypeCode∗ DDS DynamicData::get type ()

const

Get the data type, of which this DDS DynamicData (p. 622) represents an

instance.

MT Safety:

UNSAFE.

6.37.7.18 DDS TCKind DDS DynamicData::get type kind () const

Get the kind of this object’s data type.

This is a convenience method. It’s equivalent to calling DDS -

DynamicData::get type (p. 650) followed by DDS TypeCode::kind

(p. 996).

MT Safety:

UNSAFE.

6.37.7.19 DDS UnsignedLong DDS DynamicData::get member -

count () const

Get the number of members in this sample.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.37 DDS DynamicData Struct Reference 651

For objects of type kind DDS TK ARRAY (p. 66) or DDS TK -

SEQUENCE (p. 66), this method returns the number of elements in the col-

lection.

For objects of type kind DDS TK STRUCT (p. 66) or DDS TK VALUE

(p. 67), it returns the number of ﬁelds in the sample, which will always be the

same as the number of ﬁelds in the type.

For objects of type kind DDS TK SPARSE (p. 67), it returns the number of

ﬁelds in the sample, which may be less than or equal to the number of ﬁelds in

the type.

MT Safety:

UNSAFE.

See also:

DDS DynamicData::get member info by index (p. 653)

6.37.7.20 DDS Boolean DDS DynamicData::member exists (const

char ∗ member name, DDS DynamicDataMemberId

member id) const

Indicates whether a member of a particular name/ID exists in this data sample.

Only one of the name and/or ID need by speciﬁed.

For objects of type kinds other than DDS TK SPARSE (p. 67), the

result of this method will always be the same as that of DDS -

DynamicData::member exists in type (p. 652).

MT Safety:

UNSAFE.

Parameters:

member name <<in>> ( p. 200) The name of the member or NULL to

look up the member by its ID.

member id <<in>> ( p. 200) The ID of the member or DDS -

DYNAMIC DATA MEMBER ID UNSPECIFIED (p. 80) to

look up by name. See Member Names and IDs (p. 635).

See also:

DDS DynamicData::member exists in type (p. 652)

DDS DYNAMIC DATA MEMBER ID UNSPECIFIED (p. 80)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

652 Class Documentation

6.37.7.21 DDS Boolean DDS DynamicData::member -

exists in type (const char ∗ member name,

DDS DynamicDataMemberId member id) const

Indicates whether a member of a particular name/ID exists in this data sample’s

type.

Only one of the name and/or ID need by speciﬁed.

For objects of type kinds other than DDS TK SPARSE (p. 67), the

result of this method will always be the same as that of DDS -

DynamicData::member exists (p. 651).

MT Safety:

UNSAFE.

Parameters:

member name <<in>> ( p. 200) The name of the member or NULL to

look up the member by its ID.

member id <<in>> ( p. 200) The ID of the member or DDS -

DYNAMIC DATA MEMBER ID UNSPECIFIED (p. 80) to

look up by name. See Member Names and IDs (p. 635).

See also:

DDS DynamicData::member exists (p. 651)

DDS DYNAMIC DATA MEMBER ID UNSPECIFIED (p. 80)

6.37.7.22 DDS ReturnCode t DDS DynamicData::get member inf o

(DDS DynamicDataMemberInfo & info, const char

∗ membe r name, DDS DynamicDataMemberId

member id) const

Fill in the given descriptor with information about the identiﬁed member of this

DDS DynamicData (p. 622) sample.

This operation is valid for objects of DDS TCKind (p. 66) DDS TK -

ARRAY (p. 66), DDS TK SEQUENCE (p. 66), DDS TK STRUCT

(p. 66), DDS TK VALUE (p. 67), and DDS TK SPARSE (p. 67).

MT Safety:

UNSAFE.

Parameters:

info <<out>> ( p. 200) The descriptor object whose contents will be over-

written by this operations.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.37 DDS DynamicData Struct Reference 653

member name <<in>> ( p. 200) The name of the member for which to

get the info or NULL to look up the member by its ID. Only one of

the name and the ID may be unspeciﬁed.

member id <<in>> ( p. 200) The ID of the member for which

to get the info, or DDS DYNAMIC DATA MEMBER ID -

UNSPECIFIED (p. 80) to look up by name. See Member Names

and IDs (p. 635).

Returns:

One of the Standard Return Codes (p. 314)

See also:

DDS DynamicData::get member info by index (p. 653)

DDS DYNAMIC DATA MEMBER ID UNSPECIFIED (p. 80)

6.37.7.23 DDS ReturnCode t DDS DynamicData::get member -

info by index (struct DDS DynamicDataMemberInfo &

info, DDS UnsignedLong index) const

Fill in the given descriptor with information about the identiﬁed member of this

DDS DynamicData (p. 622) sample.

This operation is valid for objects of DDS TCKind (p. 66) DDS TK -

ARRAY (p. 66), DDS TK SEQUENCE (p. 66), DDS TK STRUCT

(p. 66), DDS TK VALUE (p. 67), and DDS TK SPARSE (p. 67).

MT Safety:

UNSAFE.

Parameters:

info <<out>> ( p. 200) The descriptor object whose contents will be over-

written by this operations.

index <<in>> ( p. 200) The zero-based of the member for which to get

the info.

Returns:

One of the Standard Return Codes (p. 314)

See also:

DDS DynamicData::get member info (p. 652)

DDS DynamicData::get member count (p. 650)

DDS DYNAMIC DATA MEMBER ID UNSPECIFIED (p. 80)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

654 Class Documentation

6.37.7.24 DDS ReturnCode t DDS DynamicData::get member -

type (const DDS TypeCode ∗& type out, const char

∗ membe r name, DDS DynamicDataMemberId

member id) const

Get the type of the given member of this sample.

The member can be looked up either by name or by ID.

This operation is valid for objects of DDS TCKind (p. 66) DDS TK -

ARRAY (p. 66), DDS TK SEQUENCE (p. 66), DDS TK STRUCT

(p. 66), DDS TK VALUE (p. 67), and DDS TK SPARSE (p. 67). For type

kinds DDS TK ARRAY (p. 66) and DDS TK SEQUENCE (p. 66), the in-

dex into the collec tion is taken to be one less than the ID, if speciﬁed. If this

index is valid, this operation will return the content type of this collection.

MT Safety:

UNSAFE.

Parameters:

type out <<out>> ( p. 200) If this method returned success, this argu-

ment refers to the found member’s type.

member name <<in>> ( p. 200) The name of the member or NULL to

look up the member by its ID.

member id <<in>> ( p. 200) The ID of the member or DDS -

DYNAMIC DATA MEMBER ID UNSPECIFIED (p. 80) to

look up by name. See Member Names and IDs (p. 635).

Returns:

One of the Standard Return Codes (p. 314)

See also:

DDS DynamicData::get member info (p. 652)

DDS DYNAMIC DATA MEMBER ID UNSPECIFIED (p. 80)

6.37.7.25 DDS ReturnCode t DDS DynamicData::is member key

(DDS Boolean & is key out, const char ∗ me mber name,

DDS DynamicDataMemberId member id) const

Indicates whether a given member forms part of the key of this sample’s data

type.

This operation is only valid for samples of types of kind DDS TK STRUCT

(p. 66), DDS TK VALUE (p. 67), or DDS TK SPARSE (p. 67).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.37 DDS DynamicData Struct Reference 655

Note to users of sparse types: A key member may only have a single represen-

tation and is required to exist in every sample.

MT Safety:

UNSAFE.

Parameters:

is key out <<out>> ( p. 200) If this method returned success, this argu-

ment indicates whether the indicated member is part of the key.

member name <<in>> ( p. 200) The name of the member or NULL to

look up the member by its ID.

member id <<in>> ( p. 200) The ID of the member or DDS -

DYNAMIC DATA MEMBER ID UNSPECIFIED (p. 80) to

look up by name. See Member Names and IDs (p. 635).

Returns:

One of the Standard Return Codes (p. 314)

6.37.7.26 DDS ReturnCode t DDS DynamicData::get long

(DDS Long & value out, const char ∗ member name,

DDS DynamicDataMemberId member id) const

Get the value of the given ﬁeld, which is of type DDS Long (p. 300) or

another type implicitly convertible to it (DDS Octet (p. 299), DDS Char

(p. 299), DDS Short (p. 299), DDS UnsignedShort (p. 299), or DDS -

Enum (p. 301)).

The member may be speciﬁed by name or by ID.

MT Safety:

UNSAFE.

Parameters:

value out <<out>> ( p. 200) If this method returned success, this argu-

ment will contain the value of the indicated member.

member name <<in>> ( p. 200) The name of the member or NULL to

look up the member by its ID.

member id <<in>> ( p. 200) The ID of the member or DDS -

DYNAMIC DATA MEMBER ID UNSPECIFIED (p. 80) to

look up by name. See Member Names and IDs (p. 635).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

656 Class Documentation

Returns:

One of the Standard Return Codes (p. 314)

See also:

DDS DynamicData::set long (p. 687)

6.37.7.27 DDS ReturnCode t DDS DynamicData::get short

(DDS Short & value out, const char ∗ member name,

DDS DynamicDataMemberId member id) const

Get the value of the given ﬁeld, which is of type DDS Short (p. 299) or another

type implicitly convertible to it (DDS Octet (p. 299) or DDS Char (p. 299)).

The member may be speciﬁed by name or by ID.

MT Safety:

UNSAFE.

Parameters:

value out <<out>> ( p. 200) If this method returned success, this argu-

ment will contain the value of the indicated member.

member name <<in>> ( p. 200) The name of the member or NULL to

look up the member by its ID.

member id <<in>> ( p. 200) The ID of the member or DDS -

DYNAMIC DATA MEMBER ID UNSPECIFIED (p. 80) to

look up by name. See Member Names and IDs (p. 635).

Returns:

One of the Standard Return Codes (p. 314)

See also:

DDS DynamicData::set short (p. 687)

6.37.7.28 DDS ReturnCode t DDS DynamicData::get ulong

(DDS UnsignedLong & value out, const char

∗ membe r name, DDS DynamicDataMemberId

member id) const

Get the value of the given ﬁeld, which is of type DDS UnsignedLong (p. 300)

or another type implicitly convertible to it (DDS Octet (p. 299), DDS Char

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.37 DDS DynamicData Struct Reference 657

(p. 299), DDS Short (p. 299), DDS UnsignedShort (p. 299), or DDS -

Enum (p. 301)).

The member may be speciﬁed by name or by ID.

MT Safety:

UNSAFE.

Parameters:

value out <<out>> ( p. 200) If this method returned success, this argu-

ment will contain the value of the indicated member.

member name <<in>> ( p. 200) The name of the member or NULL to

look up the member by its ID.

member id <<in>> ( p. 200) The ID of the member or DDS -

DYNAMIC DATA MEMBER ID UNSPECIFIED (p. 80) to

look up by name. See Member Names and IDs (p. 635).

Returns:

One of the Standard Return Codes (p. 314)

See also:

DDS DynamicData::set ulong (p. 688)

6.37.7.29 DDS ReturnCode t DDS DynamicData::get ushort

(DDS UnsignedShort & value out, const char

∗ membe r name, DDS DynamicDataMemberId

member id) const

Get the value of the given ﬁeld, which is of type DDS UnsignedShort (p. 299)

or another type implicitly convertible to it (DDS Octet (p. 299) or DDS Char

(p. 299)).

The member may be speciﬁed by name or by ID.

MT Safety:

UNSAFE.

Parameters:

value out <<out>> ( p. 200) If this method returned success, this argu-

ment will contain the value of the indicated member.

member name <<in>> ( p. 200) The name of the member or NULL to

look up the member by its ID.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

658 Class Documentation

member id <<in>> ( p. 200) The ID of the member or DDS -

DYNAMIC DATA MEMBER ID UNSPECIFIED (p. 80) to

look up by name. See Member Names and IDs (p. 635).

Returns:

One of the Standard Return Codes (p. 314)

See also:

DDS DynamicData::set ushort (p. 688)

6.37.7.30 DDS ReturnCode t DDS DynamicData::get ﬂoat

(DDS Float & value out, const char ∗ member name,

DDS DynamicDataMemberId member id) const

Get the value of the given ﬁeld, which is of type DDS Float (p. 300).

The member may be speciﬁed by name or by ID.

MT Safety:

UNSAFE.

Parameters:

value out <<out>> ( p. 200) If this method returned success, this argu-

ment will contain the value of the indicated member.

member name <<in>> ( p. 200) The name of the member or NULL to

look up the member by its ID.

member id <<in>> ( p. 200) The ID of the member or DDS -

DYNAMIC DATA MEMBER ID UNSPECIFIED (p. 80) to

look up by name. See Member Names and IDs (p. 635).

Returns:

One of the Standard Return Codes (p. 314)

See also:

DDS DynamicData::set ﬂoat (p. 689)

6.37.7.31 DDS ReturnCode t DDS DynamicData::get double

(DDS Double & value out, const char ∗ member name,

DDS DynamicDataMemberId member id) const

Get the value of the given ﬁeld, which is of type DDS Double (p. 300) or

another type implicitly convertible to it (DDS Float (p. 300)).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.37 DDS DynamicData Struct Reference 659

The member may be speciﬁed by name or by ID.

MT Safety:

UNSAFE.

Parameters:

value out <<out>> ( p. 200) If this method returned success, this argu-

ment will contain the value of the indicated member.

member name <<in>> ( p. 200) The name of the member or NULL to

look up the member by its ID.

member id <<in>> ( p. 200) The ID of the member or DDS -

DYNAMIC DATA MEMBER ID UNSPECIFIED (p. 80) to

look up by name. See Member Names and IDs (p. 635).

Returns:

One of the Standard Return Codes (p. 314)

See also:

DDS DynamicData::set double (p. 690)

6.37.7.32 DDS ReturnCode t DDS DynamicData::get boolean

(DDS Boolean & value out, const char ∗ member name,

DDS DynamicDataMemberId member id) const

Get the value of the given ﬁeld, which is of type DDS Boolean (p. 301).

The member may be speciﬁed by name or by ID.

MT Safety:

UNSAFE.

Parameters:

value out <<out>> ( p. 200) If this method returned success, this argu-

ment will contain the value of the indicated member.

member name <<in>> ( p. 200) The name of the member or NULL to

look up the member by its ID.

member id <<in>> ( p. 200) The ID of the member or DDS -

DYNAMIC DATA MEMBER ID UNSPECIFIED (p. 80) to

look up by name. See Member Names and IDs (p. 635).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

660 Class Documentation

Returns:

One of the Standard Return Codes (p. 314)

See also:

DDS DynamicData::set boolean (p. 690)

6.37.7.33 DDS ReturnCode t DDS DynamicData::get char

(DDS Char & value out, const char ∗ member name,

DDS DynamicDataMemberId member id) const

Get the value of the given ﬁeld, which is of type DDS Char (p. 299).

The member may be speciﬁed by name or by ID.

MT Safety:

UNSAFE.

Parameters:

value out <<out>> ( p. 200) If this method returned success, this argu-

ment will contain the value of the indicated member.

member name <<in>> ( p. 200) The name of the member or NULL to

look up the member by its ID.

member id <<in>> ( p. 200) The ID of the member or DDS -

DYNAMIC DATA MEMBER ID UNSPECIFIED (p. 80) to

look up by name. See Member Names and IDs (p. 635).

Returns:

One of the Standard Return Codes (p. 314)

See also:

DDS DynamicData::set char (p. 691)

6.37.7.34 DDS ReturnCode t DDS DynamicData::get octet

(DDS Octet & value out, const char ∗ member name,

DDS DynamicDataMemberId member id) const

Get the value of the given ﬁeld, which is of type DDS Octet (p. 299).

The member may be speciﬁed by name or by ID.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.37 DDS DynamicData Struct Reference 661

MT Safety:

UNSAFE.

Parameters:

value out <<out>> ( p. 200) If this method returned success, this argu-

ment will contain the value of the indicated member.

member name <<in>> ( p. 200) The name of the member or NULL to

look up the member by its ID.

member id <<in>> ( p. 200) The ID of the member or DDS -

DYNAMIC DATA MEMBER ID UNSPECIFIED (p. 80) to

look up by name. See Member Names and IDs (p. 635).

Returns:

One of the Standard Return Codes (p. 314)

See also:

DDS DynamicData::set octet (p. 691)

6.37.7.35 DDS ReturnCode t DDS DynamicData::get longlong

(DDS LongLong & value out, const char ∗ member name,

DDS DynamicDataMemberId member id) const

Get the value of the given ﬁeld, which is of type DDS LongLong (p. 300) or

another type implicitly convertible to it (DDS Octet (p. 299), DDS Char

(p. 299), DDS Short (p. 299), DDS UnsignedShort (p. 299), DDS Long

(p. 300), DDS UnsignedLong (p. 300), or DDS Enum (p. 301)).

The member may be speciﬁed by name or by ID.

MT Safety:

UNSAFE.

Parameters:

value out <<out>> ( p. 200) If this method returned success, this argu-

ment will contain the value of the indicated member.

member name <<in>> ( p. 200) The name of the member or NULL to

look up the member by its ID.

member id <<in>> ( p. 200) The ID of the member or DDS -

DYNAMIC DATA MEMBER ID UNSPECIFIED (p. 80) to

look up by name. See Member Names and IDs (p. 635).

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

662 Class Documentation

Returns:

One of the Standard Return Codes (p. 314)

See also:

DDS DynamicData::set longlong (p. 692)

6.37.7.36 DDS ReturnCode t DDS DynamicData::get ulonglong

(DDS UnsignedLongLong & value out, const char

∗ membe r name, DDS DynamicDataMemberId

member id) const

Get the value of the given ﬁeld, which is of type DDS UnsignedLongLong

(p. 300) or another type implicitly convertible to it (DDS Octet (p. 299),

DDS Char (p. 299), DDS Short (p. 299), DDS UnsignedShort (p. 299),

DDS Long (p. 300), DDS UnsignedLong (p. 300), or DDS Enum (p. 301)).

The member may be speciﬁed by name or by ID.

MT Safety:

UNSAFE.

Parameters:

value out <<out>> ( p. 200) If this method returned success, this argu-

ment will contain the value of the indicated member.

member name <<in>> ( p. 200) The name of the member or NULL to

look up the member by its ID.

member id <<in>> ( p. 200) The ID of the member or DDS -

DYNAMIC DATA MEMBER ID UNSPECIFIED (p. 80) to

look up by name. See Member Names and IDs (p. 635).

Returns:

One of the Standard Return Codes (p. 314)

See also:

DDS DynamicData::set ulonglong (p. 693)

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.37 DDS DynamicData Struct Reference 663

6.37.7.37 DDS ReturnCode t DDS DynamicData::get longdouble

(DDS LongDouble & value out, const char ∗

member name, DDS DynamicDataMemberId

member id) const

Get the value of the given ﬁeld, which is of type DDS LongDouble (p. 300) or

another type implicitly convertible to it (DDS Float (p. 300) or DDS Double

(p. 300)).

The member may be speciﬁed by name or by ID.

MT Safety:

UNSAFE.

Parameters:

value out <<out>> ( p. 200) If this method returned success, this argu-

ment will contain the value of the indicated member.

member name <<in>> ( p. 200) The name of the member or NULL to

look up the member by its ID.

member id <<in>> ( p. 200) The ID of the member or DDS -

DYNAMIC DATA MEMBER ID UNSPECIFIED (p. 80) to

look up by name. See Member Names and IDs (p. 635).

Returns:

One of the Standard Return Codes (p. 314)

See also:

DDS DynamicData::set longdouble (p. 693)

6.37.7.38 DDS ReturnCode t DDS DynamicData::get wchar

(DDS Wchar & value out, const char ∗ me mber name,

DDS DynamicDataMemberId member id) const

Get the value of the given ﬁeld, which is of type DDS Wchar (p. 299) or

another type implicitly convertible to it (DDS Char (p. 299)).

The member may be speciﬁed by name or by ID.

MT Safety:

UNSAFE.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

664 Class Documentation

Parameters:

value out <<out>> ( p. 200) If this method returned success, this argu-

ment will contain the value of the indicated member.

member name <<in>> ( p. 200) The name of the member or NULL to

look up the member by its ID.

member id <<in>> ( p. 200) The ID of the member or DDS -

DYNAMIC DATA MEMBER ID UNSPECIFIED (p. 80) to

look up by name. See Member Names and IDs (p. 635).

Returns:

One of the Standard Return Codes (p. 314)

See also:

DDS DynamicData::set wchar (p. 694)

6.37.7.39 DDS ReturnCode t DDS DynamicData::get string

(char ∗& value, DDS UnsignedLong ∗ size, const

char ∗ member name, DDS DynamicDataMemberId

member id) const

Get the value of the given ﬁeld, which is of type char∗.

The member may be speciﬁed by name or by ID.

MT Safety:

UNSAFE.

Parameters:

value <<out>> ( p. 200) The string into which the middleware should

copy the string member. The allocated size of this string is indicated

by size argument. If the size is suﬃcient to hold the contents of the

member, they will be copied into this string. If value is a pointer

to NULL, the middleware will allocate a new string for you of suﬃ-

cient length; it will be your responsibility to free that string. If the

size is insuﬃcient but greater than zero, the middleware will not free

your string; instead, this operation will fail and size will contain the

minimum required size.

size <<inout>> ( p. 200) As an input argument, the allocated size of the

string. As an output argument, the actual size of the contents.

member name <<in>> ( p. 200) The name of the member or NULL to

look up the member by its ID.

Generated on Mon Aug 13 09:00:30 2012 for RTI Connext C++ API by Doxygen

6.37 DDS DynamicData Struct Reference 665

member id <<in>> ( p. 200) The ID of the member or DDS -

DYNAMIC DATA MEMBER ID UNSPECIFIED (p. 80) to

look up by name. See Member Names and IDs (p. 635).

Returns:

One of the Standard Return Codes (p. 314) or DDS RETCODE -

OUT OF RESOURCES (p. 315)

See also:

DDS String alloc (p. 458)

DDS String free (p. 459)

DDS DynamicData::set string (p. 695)

6.37.7.40 DDS ReturnCode t DDS DynamicData::get wstring

(DDS Wchar ∗& value, DDS UnsignedLong ∗ size, const

char ∗ member name, DDS DynamicDataMemberId

member id) const

Get the value of the given ﬁeld, which is of type DDS Wchar (p. 299)∗.