C Reference GuideRelease 6.x

Vortex OpenSplice

C REFERENCE GUIDE

Part Number: OS-CREFG Doc Issue 65, 6 February 2018

Copyright Notice© 2006 to 2018 ADLINK Technology Limited. All rights reserved.

This document may be reproduced in whole but not in part.

The information contained in this document is subject to change without notice andis made available in good faith without liability on the part of ADLINK TechnologyLimited.

All trademarks acknowledged.

iiC Reference Guide

CONTENTS

Table of Contents

List of Figures xxi

PrefaceAbout the C Reference Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiiiContacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv

IntroductionAbout the C Reference Guide 3Document Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

API ReferenceChapter 1 DCPS API General Description 7

1.1 Thread Safety . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.2 Signal Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.2.1 Synchronous Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91.2.2 Asynchronous Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91.3 Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91.3.1 IDL Mapping Rules for Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91.3.1.1 Standard Defined Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101.3.1.2 User-Defined Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101.3.1.3 Data Distribution Service Defined Type . . . . . . . . . . . . . . . . . . . . . . . . . . 111.3.2 Plain Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.3.3 Sequences Embedded in QosPolicy Objects . . . . . . . . . . . . . . . . . . . . . . . . . 121.3.4 Sequences Embedded in Status Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.3.5 Resources and operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.3.5.1 Sequences DDS_<sequence-name> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131.3.5.2 DDS_sequence_set_release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

vC Reference Guide

Table of Contents

1.4 Listeners Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221.4.1 Struct DDS_<Entity>Listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241.4.2 DDS_DomainParticipantListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271.4.3 DDS_ExtDomainParticipantListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291.4.4 DDS_TopicListener. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321.4.5 DDS_ExtTopicListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331.4.6 DDS_PublisherListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341.4.7 DDS_DataWriterListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351.4.8 DDS_SubscriberListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361.4.9 DDS_DataReaderListener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381.5 Inheritance of Abstract Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Chapter 2 DCPS Modules 412.1 Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412.2 Infrastructure Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422.3 Domain Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432.4 Topic-Definition Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442.5 Publication Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462.6 Subscription Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Chapter 3 DCPS Classes and Operations 513.1 Infrastructure Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523.1.1 Class DDS_Entity (abstract) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523.1.1.1 DDS_Entity_enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543.1.1.2 DDS_Entity_get_instance_handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553.1.1.3 DDS_Entity_get_listener (abstract) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563.1.1.4 DDS_Entity_get_qos (abstract) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563.1.1.5 DDS_Entity_get_status_changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573.1.1.6 DDS_Entity_get_statuscondition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583.1.1.7 DDS_Entity_set_listener (abstract) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593.1.1.8 DDS_Entity_set_qos (abstract) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593.1.2 Class DDS_DomainEntity (abstract). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593.1.3 Struct QosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593.1.3.1 DDS_DeadlineQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693.1.3.2 DDS_DestinationOrderQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713.1.3.3 DDS_DurabilityQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733.1.3.4 DDS_DurabilityServiceQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763.1.3.5 DDS_EntityFactoryQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793.1.3.6 DDS_GroupDataQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803.1.3.7 DDS_HistoryQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803.1.3.8 DDS_LatencyBudgetQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 833.1.3.9 DDS_LifespanQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

viC Reference Guide

Table of Contents

3.1.3.10 DDS_LivelinessQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 853.1.3.11 DDS_OwnershipQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 873.1.3.12 DDS_OwnershipStrengthQosPolicy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 903.1.3.13 DDS_PartitionQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 913.1.3.14 DDS_PresentationQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 923.1.3.15 DDS_ReaderDataLifecycleQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . 993.1.3.16 DDS_ReliabilityQosPolicy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1023.1.3.17 DDS_ResourceLimitsQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1043.1.3.18 DDS_SchedulingQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1063.1.3.19 DDS_TimeBasedFilterQosPolicy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1073.1.3.20 DDS_TopicDataQosPolicy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1083.1.3.21 DDS_TransportPriorityQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1093.1.3.22 DDS_UserDataQosPolicy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1103.1.3.23 DDS_WriterDataLifecycleQosPolicy. . . . . . . . . . . . . . . . . . . . . . . . . . . 1103.1.3.24 DDS_SubscriptionKeyQosPolicy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1123.1.3.25 DDS_ReaderLifespanQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1133.1.3.26 DDS_ShareQosPolicy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1143.1.3.27 DDS_ViewKeyQosPolicy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1153.1.4 DDS_Listener interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1163.1.5 Struct DDS_Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1173.1.5.1 DDS_InconsistentTopicStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1223.1.5.2 DDS_LivelinessChangedStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1223.1.5.3 DDS_LivelinessLostStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1243.1.5.4 DDS_OfferedDeadlineMissedStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1253.1.5.5 DDS_OfferedIncompatibleQosStatus. . . . . . . . . . . . . . . . . . . . . . . . . . . . 1263.1.5.6 DDS_PublicationMatchedStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1283.1.5.7 DDS_RequestedDeadlineMissedStatus . . . . . . . . . . . . . . . . . . . . . . . . . . 1293.1.5.8 DDS_RequestedIncompatibleQosStatus . . . . . . . . . . . . . . . . . . . . . . . . . 1303.1.5.9 DDS_SampleLostStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1323.1.5.10 DDS_SampleRejectedStatus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1333.1.5.11 DDS_SubscriptionMatchedStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1343.1.5.12 DDS_AllDataDisposedTopicStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1353.1.6 Class DDS_WaitSet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1363.1.6.1 DDS_WaitSet__alloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1373.1.6.2 DDS_WaitSet_attach_condition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1373.1.6.3 DDS_WaitSet_detach_condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1393.1.6.4 DDS_WaitSet_get_conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1403.1.6.5 DDS_WaitSet_wait. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1413.1.7 Class DDS_Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1433.1.7.1 DDS_Condition_get_trigger_value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1443.1.8 Class DDS_GuardCondition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1453.1.8.1 DDS_GuardCondition__alloc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

viiC Reference Guide

Table of Contents

3.1.8.2 DDS_GuardCondition_get_trigger_value (inherited) . . . . . . . . . . . . . . . 1473.1.8.3 DDS_GuardCondition_set_trigger_value . . . . . . . . . . . . . . . . . . . . . . . . 1473.1.9 Class DDS_StatusCondition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1483.1.9.1 DDS_StatusCondition_get_enabled_statuses. . . . . . . . . . . . . . . . . . . . . . 1493.1.9.2 DDS_StatusCondition_get_entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1513.1.9.3 DDS_StatusCondition_get_trigger_value (inherited) . . . . . . . . . . . . . . . 1513.1.9.4 DDS_StatusCondition_set_enabled_statuses . . . . . . . . . . . . . . . . . . . . . . 1523.1.10 Class DDS_ErrorInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1533.1.10.1 DDS_ErrorInfo__alloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1553.1.10.2 DDS_ErrorInfo_update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1553.1.10.3 DDS_ErrorInfo_get_code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1563.1.10.4 DDS_ErrorInfo_get_message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1583.1.10.5 DDS_ErrorInfo_get_location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1593.1.10.6 DDS_ErrorInfo_get_source_line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1603.1.10.7 DDS_ErrorInfo_get_stack_trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1603.2 Domain Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1613.2.1 Class DDS_DomainParticipant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1613.2.1.1 DDS_DomainParticipant_assert_liveliness . . . . . . . . . . . . . . . . . . . . . . . 1663.2.1.2 DDS_DomainParticipant_contains_entity . . . . . . . . . . . . . . . . . . . . . . . . 1673.2.1.3 DDS_DomainParticipant_create_contentfilteredtopic . . . . . . . . . . . . . . . 1683.2.1.4 DDS_DomainParticipant_create_multitopic . . . . . . . . . . . . . . . . . . . . . . 1693.2.1.5 DDS_DomainParticipant_create_publisher . . . . . . . . . . . . . . . . . . . . . . . 1713.2.1.6 DDS_DomainParticipant_create_subscriber . . . . . . . . . . . . . . . . . . . . . . 1743.2.1.7 DDS_DomainParticipant_create_topic . . . . . . . . . . . . . . . . . . . . . . . . . . 1773.2.1.8 DDS_DomainParticipant_delete_contained_entities . . . . . . . . . . . . . . . . 1793.2.1.9 DDS_DomainParticipant_delete_contentfilteredtopic . . . . . . . . . . . . . . . 1813.2.1.10 DDS_DomainParticipant_delete_multitopic . . . . . . . . . . . . . . . . . . . . . 1833.2.1.11 DDS_DomainParticipant_delete_publisher . . . . . . . . . . . . . . . . . . . . . . 1843.2.1.12 DDS_DomainParticipant_delete_subscriber . . . . . . . . . . . . . . . . . . . . . 1853.2.1.13 DDS_DomainParticipant_delete_topic . . . . . . . . . . . . . . . . . . . . . . . . . 1863.2.1.14 DDS_DomainParticipant_enable (inherited) . . . . . . . . . . . . . . . . . . . . . 1883.2.1.15 DDS_DomainParticipant_find_topic . . . . . . . . . . . . . . . . . . . . . . . . . . . 1883.2.1.16 DDS_DomainParticipant_get_builtin_subscriber . . . . . . . . . . . . . . . . . 1903.2.1.17 DDS_DomainParticipant_get_current_time. . . . . . . . . . . . . . . . . . . . . . 1903.2.1.18 DDS_DomainParticipant_get_default_publisher_qos . . . . . . . . . . . . . . 1923.2.1.19 DDS_DomainParticipant_get_default_subscriber_qos . . . . . . . . . . . . . 1933.2.1.20 DDS_DomainParticipant_get_default_topic_qos . . . . . . . . . . . . . . . . . 1953.2.1.21 DDS_DomainParticipant_get_discovered_participants . . . . . . . . . . . . . 1963.2.1.22 DDS_DomainParticipant_get_discovered_participant_data . . . . . . . . . 1983.2.1.23 DDS_DomainParticipant_get_discovered_topics . . . . . . . . . . . . . . . . . 1993.2.1.24 DDS_DomainParticipant_get_discovered_topic_data . . . . . . . . . . . . . . 2013.2.1.25 DDS_DomainParticipant_get_domain_id . . . . . . . . . . . . . . . . . . . . . . . 202

viiiC Reference Guide

Table of Contents

3.2.1.26 DDS_DomainParticipant_get_listener . . . . . . . . . . . . . . . . . . . . . . . . . . 2033.2.1.27 DDS_DomainParticipant_get_qos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2043.2.1.28 DDS_DomainParticipant_get_status_changes (inherited) . . . . . . . . . . . 2053.2.1.29 DDS_DomainParticipant_get_statuscondition (inherited) . . . . . . . . . . . 2053.2.1.30 DDS_DomainParticipant_ignore_participant. . . . . . . . . . . . . . . . . . . . . 2053.2.1.31 DDS_DomainParticipant_ignore_publication . . . . . . . . . . . . . . . . . . . . 2063.2.1.32 DDS_DomainParticipant_ignore_subscription . . . . . . . . . . . . . . . . . . . 2063.2.1.33 DDS_DomainParticipant_ignore_topic . . . . . . . . . . . . . . . . . . . . . . . . . 2063.2.1.34 DDS_DomainParticipant_lookup_topicdescription . . . . . . . . . . . . . . . . 2063.2.1.35 DDS_DomainParticipant_set_default_publisher_qos . . . . . . . . . . . . . . 2073.2.1.36 DDS_DomainParticipant_set_default_subscriber_qos. . . . . . . . . . . . . . 2093.2.1.37 DDS_DomainParticipant_set_default_topic_qos . . . . . . . . . . . . . . . . . . 2103.2.1.38 DDS_DomainParticipant_set_listener . . . . . . . . . . . . . . . . . . . . . . . . . . 2123.2.1.39 DDS_DomainParticipant_set_qos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2153.2.1.40 DDS_DomainParticipant_delete_historical_data . . . . . . . . . . . . . . . . . . 2163.2.1.41 DDS_DomainParticipant_get_property . . . . . . . . . . . . . . . . . . . . . . . . . 2173.2.1.42 DDS_DomainParticipant_set_property . . . . . . . . . . . . . . . . . . . . . . . . . 2183.2.2 Class DDS_DomainParticipantFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2203.2.2.1 DDS_DomainParticipantFactory_create_participant . . . . . . . . . . . . . . . . 2213.2.2.2 DDS_DomainParticipantFactory_delete_participant . . . . . . . . . . . . . . . . 2253.2.2.3 DDS_DomainParticipantFactory_get_default_participant_qos . . . . . . . . 2263.2.2.4 DDS_DomainParticipantFactory_get_instance . . . . . . . . . . . . . . . . . . . . 2273.2.2.5 DDS_DomainParticipantFactory_get_qos . . . . . . . . . . . . . . . . . . . . . . . . 2283.2.2.6 DDS_DomainParticipantFactory_lookup_participant . . . . . . . . . . . . . . . 2293.2.2.7 DDS_DomainParticipantFactory_set_default_participant_qos . . . . . . . . 2303.2.2.8 DDS_DomainParticipantFactory_set_qos . . . . . . . . . . . . . . . . . . . . . . . . 2313.2.2.9 DDS_DomainParticipantFactory_delete_domain . . . . . . . . . . . . . . . . . . 2323.2.2.10 DDS_DomainParticipantFactory_lookup_domain. . . . . . . . . . . . . . . . . 2333.2.2.11 DDS_DomainParticipantFactory_delete_contained_entities . . . . . . . . . 2343.2.2.12 DDS_DomainParticipantFactory_detach_all_domains . . . . . . . . . . . . . 2353.2.3 Class DDS_Domain. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2373.2.3.1 DDS_Domain_create_persistent_snapshot. . . . . . . . . . . . . . . . . . . . . . . . 2383.2.4 DDS_DomainParticipantListener interface . . . . . . . . . . . . . . . . . . . . . . . . . 2393.2.4.1 DDS_DomainParticipantListener__alloc . . . . . . . . . . . . . . . . . . . . . . . . . 2423.2.4.2 DDS_DomainParticipantListener_on_data_available (inherited, abstract) . . . . . . . . . . . . 2433.2.4.3 DDS_DomainParticipantListener_on_data_on_readers (inherited, abstract) . . . . . . . . . . . . 2433.2.4.4 DDS_DomainParticipantListener_on_inconsistent_topic (inherited, abstract) . . . . . . . . . . . . 2433.2.4.5 DDS_DomainParticipantListener_on_liveliness_changed (inherited, abstract) . . . . . . . . . . . . 243

ixC Reference Guide

Table of Contents

3.2.4.6 DDS_DomainParticipantListener_on_liveliness_lost (inherited, abstract) . . . . . . . . . . . . 2443.2.4.7 DDS_DomainParticipantListener_on_offered_deadline_missed (inherited, abstract) . . . . . . . . . . . . 2443.2.4.8 DDS_DomainParticipantListener_on_offered_incompatible_qos (inherited, abstract) . . . . . . . . . . . . 2443.2.4.9 DDS_DomainParticipantListener_on_publication_matched (inherited, abstract) . . . . . . . . . . . . 2453.2.4.10 DDS_DomainParticipantListener_on_requested_deadline_missed (inherited, abstract) . . . . . . . . . . . . 2453.2.4.11 DDS_DomainParticipantListener_on_requested_incompatible_qos (inherited, abstract) . . . . . . . . . . . . 2453.2.4.12 DDS_DomainParticipantListener_on_sample_lost (inherited, abstract) 2463.2.4.13 DDS_DomainParticipantListener_on_sample_rejected (inherited, abstract) . . . . . . . . . . . . 2463.2.4.14 DDS_DomainParticipantListener_on_subscription_matched (inherited, abstract) . . . . . . . . . . . . 2463.2.5 DDS_ExtDomainParticipantListener interface . . . . . . . . . . . . . . . . . . . . . . 2463.2.5.1 DDS_ExtDomainParticipantListener__alloc . . . . . . . . . . . . . . . . . . . . . . 2493.2.5.2 DDS_ExtDomainParticipantListener_on_data_available (inherited, abstract) . . . . . . . . . . . . 2503.2.5.3 DDS_ExtDomainParticipantListener_on_data_on_readers (inherited, abstract) . . . . . . . . . . . . 2503.2.5.4 DDS_ExtDomainParticipantListener_on_inconsistent_topic (inherited, abstract) . . . . . . . . . . . . 2503.2.5.5 DDS_ExtDomainParticipantListener_on_liveliness_changed (inherited, abstract) . . . . . . . . . . . . 2513.2.5.6 DDS_ExtDomainParticipantListener_on_liveliness_lost (inherited, abstract) . . . . . . . . . . . . 2513.2.5.7 DDS_ExtDomainParticipantListener_on_offered_deadline_missed (inherited, abstract) . . . . . . . . . . . . 2513.2.5.8 DDS_ExtDomainParticipantListener_on_offered_incompatible_qos (inherited, abstract) . . . . . . . . . . . . 2513.2.5.9 DDS_ExtDomainParticipantListener_on_publication_matched (inherited, abstract) . . . . . . . . . . . . 2523.2.5.10 DDS_ExtDomainParticipantListener_on_requested_deadline_missed (inherited, abstract) . . . . . . . . . . . . 2523.2.5.11 DDS_ExtDomainParticipantListener_on_requested_incompatible_qos (inherited, abstract) . . . . . . . . . . . . 2523.2.5.12 DDS_ExtDomainParticipantListener_on_sample_lost (inherited, abstract) . . . . . . . . . . . . 253

xC Reference Guide

Table of Contents

3.2.5.13 DDS_ExtDomainParticipantListener_on_sample_rejected (inherited, abstract) . . . . . . . . . . . . 2533.2.5.14 DDS_ExtDomainParticipantListener_on_subscription_matched (inherited, abstract) . . . . . . . . . . . . 2533.2.5.15 DDS_ExtDomainParticipantListener_on_all_data_disposed (inherited, abstract) . . . . . . . . . . . . 2533.3 Topic-Definition Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2543.3.1 Class DDS_TopicDescription (abstract) . . . . . . . . . . . . . . . . . . . . . . . . . . . 2553.3.1.1 DDS_TopicDescription_get_name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2563.3.1.2 DDS_TopicDescription_get_participant . . . . . . . . . . . . . . . . . . . . . . . . . 2563.3.1.3 DDS_TopicDescription_get_type_name . . . . . . . . . . . . . . . . . . . . . . . . . 2573.3.2 Class DDS_Topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2583.3.2.1 DDS_Topic_enable (inherited). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2593.3.2.2 DDS_Topic_get_inconsistent_topic_status . . . . . . . . . . . . . . . . . . . . . . . 2603.3.2.3 DDS_Topic_get_listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2613.3.2.4 DDS_Topic_get_name (inherited) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2613.3.2.5 DDS_Topic_get_participant (inherited) . . . . . . . . . . . . . . . . . . . . . . . . . . 2613.3.2.6 DDS_Topic_get_qos. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2623.3.2.7 DDS_Topic_get_status_changes (inherited) . . . . . . . . . . . . . . . . . . . . . . 2633.3.2.8 DDS_Topic_get_statuscondition (inherited) . . . . . . . . . . . . . . . . . . . . . . 2633.3.2.9 DDS_Topic_get_type_name (inherited). . . . . . . . . . . . . . . . . . . . . . . . . . 2633.3.2.10 DDS_Topic_set_listener. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2633.3.2.11 DDS_Topic_set_qos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2653.3.2.12 DDS_Topic_dispose_all_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2673.3.3 Class DDS_ContentFilteredTopic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2683.3.3.1 DDS_ContentFilteredTopic_get_expression_parameters . . . . . . . . . . . . 2703.3.3.2 DDS_ContentFilteredTopic_get_filter_expression . . . . . . . . . . . . . . . . . 2713.3.3.3 DDS_ContentFilteredTopic_get_name (inherited) . . . . . . . . . . . . . . . . . 2713.3.3.4 DDS_ContentFilteredTopic_get_participant (inherited) . . . . . . . . . . . . . 2723.3.3.5 DDS_ContentFilteredTopic_get_related_topic . . . . . . . . . . . . . . . . . . . . 2723.3.3.6 DDS_ContentFilteredTopic_get_type_name (inherited) . . . . . . . . . . . . . 2733.3.3.7 DDS_ContentFilteredTopic_set_expression_parameters. . . . . . . . . . . . . 2733.3.4 Class DDS_MultiTopic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2733.3.4.1 DDS_MultiTopic_get_expression_parameters. . . . . . . . . . . . . . . . . . . . . 2743.3.4.2 DDS_MultiTopic_get_name (inherited). . . . . . . . . . . . . . . . . . . . . . . . . . 2753.3.4.3 DDS_MultiTopic_get_participant (inherited) . . . . . . . . . . . . . . . . . . . . . 2763.3.4.4 DDS_MultiTopic_get_subscription_expression. . . . . . . . . . . . . . . . . . . . 2763.3.4.5 DDS_MultiTopic_get_type_name (inherited) . . . . . . . . . . . . . . . . . . . . . 2773.3.4.6 DDS_MultiTopic_set_expression_parameters . . . . . . . . . . . . . . . . . . . . . 2773.3.5 DDS_TopicListener Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2783.3.5.1 DDS_TopicListener__alloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2793.3.5.2 DDS_TopicListener_on_inconsistent_topic (abstract). . . . . . . . . . . . . . . 280

xiC Reference Guide

Table of Contents

3.3.6 DDS_ExtTopicListener interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2813.3.6.1 DDS_ExtTopicListener_on_all_data_disposed (abstract) . . . . . . . . . . . . 2823.3.7 Topic-Definition Type Specific Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . 2833.3.7.1 Class DDS_TypeSupport (abstract) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2833.3.7.2 DDS_TypeSupport__alloc (abstract) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2843.3.7.3 DDS_TypeSupport_get_type_name (abstract). . . . . . . . . . . . . . . . . . . . . 2843.3.7.4 DDS_TypeSupport_register_type (abstract) . . . . . . . . . . . . . . . . . . . . . . 2843.3.7.5 Class SPACE_FooTypeSupport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2853.3.7.6 SPACE_FooTypeSupport__alloc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2853.3.7.7 SPACE_FooTypeSupport_get_type_name . . . . . . . . . . . . . . . . . . . . . . . 2863.3.7.8 SPACE_FooTypeSupport_register_type . . . . . . . . . . . . . . . . . . . . . . . . . 2873.4 Publication Module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2893.4.1 Class DDS_Publisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2903.4.1.1 DDS_Publisher_begin_coherent_changes . . . . . . . . . . . . . . . . . . . . . . . . 2923.4.1.2 DDS_Publisher_copy_from_topic_qos . . . . . . . . . . . . . . . . . . . . . . . . . . 2943.4.1.3 DDS_Publisher_create_datawriter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2953.4.1.4 DDS_Publisher_delete_contained_entities . . . . . . . . . . . . . . . . . . . . . . . 2993.4.1.5 DDS_Publisher_delete_datawriter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3003.4.1.6 DDS_Publisher_enable (inherited). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3013.4.1.7 DDS_Publisher_end_coherent_changes. . . . . . . . . . . . . . . . . . . . . . . . . . 3013.4.1.8 DDS_Publisher_get_default_datawriter_qos . . . . . . . . . . . . . . . . . . . . . . 3023.4.1.9 DDS_Publisher_get_listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3043.4.1.10 DDS_Publisher_get_participant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3043.4.1.11 DDS_Publisher_get_qos. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3053.4.1.12 DDS_Publisher_get_status_changes (inherited) . . . . . . . . . . . . . . . . . . 3063.4.1.13 DDS_Publisher_get_statuscondition (inherited) . . . . . . . . . . . . . . . . . . 3063.4.1.14 DDS_Publisher_lookup_datawriter . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3063.4.1.15 DDS_Publisher_resume_publications . . . . . . . . . . . . . . . . . . . . . . . . . . 3073.4.1.16 DDS_Publisher_set_default_datawriter_qos . . . . . . . . . . . . . . . . . . . . . 3083.4.1.17 DDS_Publisher_set_listener. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3103.4.1.18 DDS_Publisher_set_qos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3123.4.1.19 DDS_Publisher_suspend_publications. . . . . . . . . . . . . . . . . . . . . . . . . . 3143.4.1.20 DDS_Publisher_wait_for_acknowledgments. . . . . . . . . . . . . . . . . . . . . 3153.4.2 Publication Type Specific Classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3173.4.2.1 Class DDS_DataWriter (abstract) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3173.4.2.2 DDS_DataWriter_assert_liveliness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3213.4.2.3 DDS_DataWriter_dispose (abstract) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3233.4.2.4 DDS_DataWriter_dispose_w_timestamp (abstract). . . . . . . . . . . . . . . . . 3233.4.2.5 DDS_DataWriter_enable (inherited) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3233.4.2.6 DDS_DataWriter_get_key_value (abstract). . . . . . . . . . . . . . . . . . . . . . . 3243.4.2.7 DDS_DataWriter_get_listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3243.4.2.8 DDS_DataWriter_get_liveliness_lost_status . . . . . . . . . . . . . . . . . . . . . . 324

xiiC Reference Guide

Table of Contents

3.4.2.9 DDS_DataWriter_get_matched_subscription_data . . . . . . . . . . . . . . . . . 3263.4.2.10 DDS_DataWriter_get_matched_subscriptions. . . . . . . . . . . . . . . . . . . . 3273.4.2.11 DDS_DataWriter_get_offered_deadline_missed_status . . . . . . . . . . . . 3293.4.2.12 DDS_DataWriter_get_offered_incompatible_qos_status . . . . . . . . . . . 3303.4.2.13 DDS_DataWriter_get_publication_matched_status. . . . . . . . . . . . . . . . 3323.4.2.14 DDS_DataWriter_get_publisher. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3333.4.2.15 DDS_DataWriter_get_qos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3343.4.2.16 DDS_DataWriter_get_status_changes (inherited) . . . . . . . . . . . . . . . . . 3353.4.2.17 DDS_DataWriter_get_statuscondition (inherited) . . . . . . . . . . . . . . . . . 3353.4.2.18 DDS_DataWriter_get_topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3353.4.2.19 DDS_DataWriter_lookup_instance (abstract) . . . . . . . . . . . . . . . . . . . . 3363.4.2.20 DDS_DataWriter_register_instance (abstract) . . . . . . . . . . . . . . . . . . . . 3363.4.2.21 DDS_DataWriter_register_instance_w_timestamp (abstract) . . . . . . . . 3373.4.2.22 DDS_DataWriter_set_listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3373.4.2.23 DDS_DataWriter_set_qos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3393.4.2.24 DDS_DataWriter_unregister_instance (abstract) . . . . . . . . . . . . . . . . . . 3413.4.2.25 DDS_DataWriter_unregister_instance_w_timestamp (abstract) . . . . . . 3413.4.2.26 DDS_DataWriter_wait_for_acknowledgments . . . . . . . . . . . . . . . . . . . 3423.4.2.27 DDS_DataWriter_write (abstract) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3443.4.2.28 DDS_DataWriter_write_w_timestamp (abstract) . . . . . . . . . . . . . . . . . 3443.4.2.29 DDS_DataWriter_writedispose (abstract) . . . . . . . . . . . . . . . . . . . . . . . 3443.4.2.30 DDS_DataWriter_writedispose_w_timestamp (abstract) . . . . . . . . . . . 3453.4.2.31 Class SPACE_FooDataWriter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3453.4.2.32 SPACE_FooDataWriter_assert_liveliness (inherited) . . . . . . . . . . . . . . 3493.4.2.33 SPACE_FooDataWriter_dispose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3493.4.2.34 SPACE_FooDataWriter_dispose_w_timestamp . . . . . . . . . . . . . . . . . . 3533.4.2.35 SPACE_FooDataWriter_enable (inherited) . . . . . . . . . . . . . . . . . . . . . . 3553.4.2.36 SPACE_FooDataWriter_get_key_value . . . . . . . . . . . . . . . . . . . . . . . . 3553.4.2.37 SPACE_FooDataWriter_get_listener (inherited) . . . . . . . . . . . . . . . . . . 3563.4.2.38 SPACE_FooDataWriter_get_liveliness_lost_status (inherited) . . . . . . . 3573.4.2.39 SPACE_FooDataWriter_get_matched_subscription_data (inherited) . . 3573.4.2.40 SPACE_FooDataWriter_get_matched_subscriptions (inherited) . . . . . 3573.4.2.41 SPACE_FooDataWriter_get_offered_deadline_missed_status (inherited) . . . . . . . . . . . . . . . . . . . 3573.4.2.42 SPACE_FooDataWriter_get_offered_incompatible_qos_status (inherited) . . . . . . . . . . . . . . . . . . . 3583.4.2.43 SPACE_FooDataWriter_get_publication_matched_status (inherited) . 3583.4.2.44 SPACE_FooDataWriter_get_publisher (inherited) . . . . . . . . . . . . . . . . 3583.4.2.45 SPACE_FooDataWriter_get_qos (inherited) . . . . . . . . . . . . . . . . . . . . . 3583.4.2.46 SPACE_FooDataWriter_get_status_changes (inherited) . . . . . . . . . . . . 3593.4.2.47 SPACE_FooDataWriter_get_statuscondition (inherited). . . . . . . . . . . . 3593.4.2.48 SPACE_FooDataWriter_get_topic (inherited) . . . . . . . . . . . . . . . . . . . . 359

xiiiC Reference Guide

Table of Contents

3.4.2.49 SPACE_FooDataWriter_lookup_instance . . . . . . . . . . . . . . . . . . . . . . . 3593.4.2.50 SPACE_FooDataWriter_register_instance . . . . . . . . . . . . . . . . . . . . . . 3613.4.2.51 SPACE_FooDataWriter_register_instance_w_timestamp. . . . . . . . . . . 3633.4.2.52 SPACE_FooDataWriter_set_listener (inherited) . . . . . . . . . . . . . . . . . . 3643.4.2.53 SPACE_FooDataWriter_set_qos (inherited) . . . . . . . . . . . . . . . . . . . . . 3653.4.2.54 SPACE_FooDataWriter_unregister_instance . . . . . . . . . . . . . . . . . . . . 3653.4.2.55 SPACE_FooDataWriter_unregister_instance_w_timestamp. . . . . . . . . 3693.4.2.56 SPACE_FooDataWriter_wait_for_acknowledgments (inherited) . . . . . 3703.4.2.57 SPACE_FooDataWriter_write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3713.4.2.58 SPACE_FooDataWriter_write_w_timestamp . . . . . . . . . . . . . . . . . . . . 3743.4.2.59 SPACE_FooDataWriter_writedispose . . . . . . . . . . . . . . . . . . . . . . . . . . 3753.4.2.60 SPACE_FooDataWriter_writedispose_w_timestamp . . . . . . . . . . . . . . 3803.4.3 DDS_PublisherListener interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3813.4.3.1 DDS_PublisherListener__alloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3833.4.3.2 DDS_PublisherListener_on_liveliness_lost (inherited, abstract) . . . . . . . . . . . . 3833.4.3.3 DDS_PublisherListener_on_offered_deadline_missed (inherited, abstract) . . . . . . . . . . . . 3843.4.3.4 DDS_PublisherListener_on_offered_incompatible_qos (inherited, abstract) . . . . . . . . . . . . 3843.4.3.5 DDS_PublisherListener_on_publication_matched (inherited, abstract) . 3843.4.4 DDS_DataWriterListener interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3853.4.4.1 DDS_DataWriterListener__alloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3863.4.4.2 DDS_DataWriterListener_on_liveliness_lost (abstract) . . . . . . . . . . . . . 3873.4.4.3 DDS_DataWriterListener_on_offered_deadline_missed (abstract). . . . . 3883.4.4.4 DDS_DataWriterListener_on_offered_incompatible_qos (abstract) . . . . 3893.4.4.5 DDS_DataWriterListener_on_publication_matched (abstract) . . . . . . . . 3903.5 Subscription Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3913.5.1 Class DDS_Subscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3923.5.1.1 DDS_Subscriber_begin_access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3953.5.1.2 DDS_Subscriber_copy_from_topic_qos . . . . . . . . . . . . . . . . . . . . . . . . . 3963.5.1.3 DDS_Subscriber_create_datareader. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3983.5.1.4 DDS_Subscriber_delete_contained_entities . . . . . . . . . . . . . . . . . . . . . . 4013.5.1.5 DDS_Subscriber_delete_datareader. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4033.5.1.6 DDS_Subscriber_enable (inherited). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4043.5.1.7 DDS_Subscriber_end_access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4053.5.1.8 DDS_Subscriber_get_datareaders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4063.5.1.9 DDS_Subscriber_get_default_datareader_qos. . . . . . . . . . . . . . . . . . . . . 4083.5.1.10 DDS_Subscriber_get_listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4093.5.1.11 DDS_Subscriber_get_participant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4103.5.1.12 DDS_Subscriber_get_qos. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4113.5.1.13 DDS_Subscriber_get_status_changes (inherited) . . . . . . . . . . . . . . . . . 412

xivC Reference Guide

Table of Contents

3.5.1.14 DDS_Subscriber_get_statuscondition (inherited) . . . . . . . . . . . . . . . . . 4123.5.1.15 DDS_Subscriber_lookup_datareader . . . . . . . . . . . . . . . . . . . . . . . . . . . 4123.5.1.16 DDS_Subscriber_notify_datareaders . . . . . . . . . . . . . . . . . . . . . . . . . . . 4133.5.1.17 DDS_Subscriber_set_default_datareader_qos . . . . . . . . . . . . . . . . . . . . 4143.5.1.18 DDS_Subscriber_set_listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4163.5.1.19 DDS_Subscriber_set_qos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4193.5.2 Subscription Type Specific Classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4203.5.2.1 Class DDS_DataReader (abstract) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4213.5.2.2 DDS_DataReader_create_querycondition . . . . . . . . . . . . . . . . . . . . . . . . 4273.5.2.3 DDS_DataReader_create_readcondition . . . . . . . . . . . . . . . . . . . . . . . . . 4283.5.2.4 DDS_DataReader_create_view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4303.5.2.5 DDS_DataReader_delete_contained_entities. . . . . . . . . . . . . . . . . . . . . . 4303.5.2.6 DDS_DataReader_delete_readcondition . . . . . . . . . . . . . . . . . . . . . . . . . 4323.5.2.7 DDS_DataReader_delete_view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4333.5.2.8 DDS_DataReader_enable (inherited) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4343.5.2.9 DDS_DataReader_get_default_datareaderview_qos . . . . . . . . . . . . . . . . 4343.5.2.10 DDS_DataReader_get_key_value (abstract) . . . . . . . . . . . . . . . . . . . . . 4353.5.2.11 DDS_DataReader_get_listener. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4363.5.2.12 DDS_DataReader_get_liveliness_changed_status . . . . . . . . . . . . . . . . . 4363.5.2.13 DDS_DataReader_get_matched_publication_data . . . . . . . . . . . . . . . . 4373.5.2.14 DDS_DataReader_get_matched_publications . . . . . . . . . . . . . . . . . . . . 4393.5.2.15 DDS_DataReader_get_qos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4413.5.2.16 DDS_DataReader_get_requested_deadline_missed_status . . . . . . . . . . 4423.5.2.17 DDS_DataReader_get_requested_incompatible_qos_status . . . . . . . . . 4433.5.2.18 DDS_DataReader_get_sample_lost_status . . . . . . . . . . . . . . . . . . . . . . 4443.5.2.19 DDS_DataReader_get_sample_rejected_status . . . . . . . . . . . . . . . . . . . 4463.5.2.20 DDS_DataReader_get_status_changes (inherited). . . . . . . . . . . . . . . . . 4473.5.2.21 DDS_DataReader_get_statuscondition (inherited) . . . . . . . . . . . . . . . . 4473.5.2.22 DDS_DataReader_get_subscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4473.5.2.23 DDS_DataReader_get_subscription_matched_status . . . . . . . . . . . . . . 4483.5.2.24 DDS_DataReader_get_topicdescription. . . . . . . . . . . . . . . . . . . . . . . . . 4493.5.2.25 DDS_DataReader_lookup_instance (abstract) . . . . . . . . . . . . . . . . . . . . 4503.5.2.26 DDS_DataReader_read (abstract) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4503.5.2.27 DDS_DataReader_read_instance (abstract) . . . . . . . . . . . . . . . . . . . . . . 4513.5.2.28 DDS_DataReader_read_next_instance (abstract) . . . . . . . . . . . . . . . . . 4513.5.2.29 DDS_DataReader_read_next_instance_w_condition (abstract) . . . . . . 4523.5.2.30 DDS_DataReader_read_next_sample (abstract) . . . . . . . . . . . . . . . . . . 4523.5.2.31 DDS_DataReader_read_w_condition (abstract) . . . . . . . . . . . . . . . . . . 4523.5.2.32 DDS_DataReader_return_loan (abstract) . . . . . . . . . . . . . . . . . . . . . . . . 4533.5.2.33 DDS_DataReader_set_default_datareaderview_qos . . . . . . . . . . . . . . . 4533.5.2.34 DDS_DataReader_set_listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4543.5.2.35 DDS_DataReader_set_qos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457

xvC Reference Guide

Table of Contents

3.5.2.36 DDS_DataReader_take (abstract). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4583.5.2.37 DDS_DataReader_take_instance (abstract) . . . . . . . . . . . . . . . . . . . . . . 4593.5.2.38 DDS_DataReader_take_next_instance (abstract). . . . . . . . . . . . . . . . . . 4593.5.2.39 DDS_DataReader_take_next_instance_w_condition (abstract). . . . . . . 4603.5.2.40 DDS_DataReader_take_next_sample (abstract) . . . . . . . . . . . . . . . . . . 4603.5.2.41 DDS_DataReader_take_w_condition (abstract). . . . . . . . . . . . . . . . . . . 4613.5.2.42 DDS_DataReader_wait_for_historical_data . . . . . . . . . . . . . . . . . . . . . 4613.5.2.43 DDS_DataReader_wait_for_historical_data_w_condition . . . . . . . . . . 4633.5.2.44 Class SPACE_FooDataReader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4653.5.2.45 SPACE_FooDataReader_create_querycondition (inherited) . . . . . . . . . 4713.5.2.46 SPACE_FooDataReader_create_readcondition (inherited) . . . . . . . . . . 4713.5.2.47 SPACE_FooDataReader_delete_contained_entities (inherited) . . . . . . 4723.5.2.48 SPACE_FooDataReader_delete_readcondition (inherited) . . . . . . . . . . 4723.5.2.49 SPACE_FooDataReader_enable (inherited) . . . . . . . . . . . . . . . . . . . . . 4723.5.2.50 SPACE_FooDataReader_get_key_value . . . . . . . . . . . . . . . . . . . . . . . . 4723.5.2.51 SPACE_FooDataReader_get_listener (inherited) . . . . . . . . . . . . . . . . . 4743.5.2.52 SPACE_FooDataReader_get_liveliness_changed_status (inherited) . . 4743.5.2.53 SPACE_FooDataReader_get_matched_publication_data (inherited) . . 4743.5.2.54 SPACE_FooDataReader_get_matched_publications (inherited). . . . . . 4743.5.2.55 SPACE_FooDataReader_get_qos (inherited) . . . . . . . . . . . . . . . . . . . . 4753.5.2.56 SPACE_FooDataReader_get_requested_deadline_missed_status (inherited) . . . . . . . . . . . . . . . . . . . 4753.5.2.57 SPACE_FooDataReader_get_requested_incompatible_qos_status (inherited) . . . . . . . . . . . . . . . . . . . 4753.5.2.58 SPACE_FooDataReader_get_sample_lost_status (inherited) . . . . . . . . 4763.5.2.59 SPACE_FooDataReader_get_sample_rejected_status (inherited). . . . . 4763.5.2.60 SPACE_FooDataReader_get_status_changes (inherited) . . . . . . . . . . . 4763.5.2.61 SPACE_FooDataReader_get_statuscondition (inherited) . . . . . . . . . . . 4763.5.2.62 SPACE_FooDataReader_get_subscriber (inherited) . . . . . . . . . . . . . . . 4773.5.2.63 SPACE_FooDataReader_get_subscription_matched_status (inherited) 4773.5.2.64 SPACE_FooDataReader_get_topicdescription (inherited) . . . . . . . . . . 4773.5.2.65 SPACE_FooDataReader_lookup_instance . . . . . . . . . . . . . . . . . . . . . . 4773.5.2.66 SPACE_FooDataReader_read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4783.5.2.67 SPACE_FooDataReader_read_instance. . . . . . . . . . . . . . . . . . . . . . . . . 4833.5.2.68 SPACE_FooDataReader_read_next_instance . . . . . . . . . . . . . . . . . . . . 4853.5.2.69 SPACE_FooDataReader_read_next_instance_w_condition . . . . . . . . . 4883.5.2.70 SPACE_FooDataReader_read_next_sample . . . . . . . . . . . . . . . . . . . . . 4903.5.2.71 SPACE_FooDataReader_read_w_condition . . . . . . . . . . . . . . . . . . . . . 4903.5.2.72 SPACE_FooDataReader_return_loan . . . . . . . . . . . . . . . . . . . . . . . . . . 4923.5.2.73 SPACE_FooDataReader_set_listener (inherited). . . . . . . . . . . . . . . . . . 4943.5.2.74 SPACE_FooDataReader_set_qos (inherited). . . . . . . . . . . . . . . . . . . . . 4953.5.2.75 SPACE_FooDataReader_take . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495

xviC Reference Guide

Table of Contents

3.5.2.76 SPACE_FooDataReader_take_instance . . . . . . . . . . . . . . . . . . . . . . . . . 4973.5.2.77 SPACE_FooDataReader_take_next_instance . . . . . . . . . . . . . . . . . . . . 4993.5.2.78 SPACE_FooDataReader_take_next_instance_w_condition . . . . . . . . . 5013.5.2.79 SPACE_FooDataReader_take_next_sample . . . . . . . . . . . . . . . . . . . . . 5033.5.2.80 SPACE_FooDataReader_take_w_condition . . . . . . . . . . . . . . . . . . . . . 5033.5.2.81 SPACE_FooDataReader_wait_for_historical_data (inherited) . . . . . . . 5053.5.2.82 SPACE_FooDataReader_wait_for_historical_data_w_condition (inherited) . . . . . . . . . . . . . . . . . . . 5053.5.3 Class DDS_DataSample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5053.5.4 Struct DDS_SampleInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5063.5.4.1 DDS_SampleInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5063.5.5 DDS_SubscriberListener Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5103.5.5.1 DDS_SubscriberListener__alloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5123.5.5.2 DDS_SubscriberListener_on_data_available (inherited, abstract). . . . . . 5133.5.5.3 DDS_SubscriberListener_on_data_on_readers (abstract) . . . . . . . . . . . . 5133.5.5.4 DDS_SubscriberListener_on_liveliness_changed (inherited, abstract) . . 5143.5.5.5 DDS_SubscriberListener_on_requested_deadline_missed (inherited, abstract) . . . . . . . . . . . . 5143.5.5.6 DDS_SubscriberListener_on_requested_incompatible_qos (inherited, abstract) . . . . . . . . . . . . 5153.5.5.7 DDS_SubscriberListener_on_sample_lost (inherited, abstract). . . . . . . . 5153.5.5.8 DDS_SubscriberListener_on_sample_rejected (inherited, abstract) . . . . 5153.5.5.9 DDS_SubscriberListener_on_subscription_matched (inherited, abstract) . . . . . . . . . . . . 5153.5.6 DDS_DataReaderListener interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5163.5.6.1 DDS_DataReaderListener__alloc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5173.5.6.2 DDS_DataReaderListener_on_data_available (abstract) . . . . . . . . . . . . . 5183.5.6.3 DDS_DataReaderListener_on_liveliness_changed (abstract) . . . . . . . . . 5193.5.6.4 DDS_DataReaderListener_on_requested_deadline_missed (abstract) . . 5203.5.6.5 DDS_DataReaderListener_on_requested_incompatible_qos (abstract) . 5213.5.6.6 DDS_DataReaderListener_on_sample_lost (abstract) . . . . . . . . . . . . . . . 5223.5.6.7 DDS_DataReaderListener_on_sample_rejected (abstract) . . . . . . . . . . . 5223.5.6.8 DDS_DataReaderListener_on_subscription_matched (abstract) . . . . . . . 5233.5.7 Class DDS_ReadCondition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5253.5.7.1 DDS_ReadCondition_get_datareader. . . . . . . . . . . . . . . . . . . . . . . . . . . . 5263.5.7.2 DDS_ReadCondition_get_instance_state_mask . . . . . . . . . . . . . . . . . . . 5263.5.7.3 DDS_ReadCondition_get_sample_state_mask . . . . . . . . . . . . . . . . . . . . 5273.5.7.4 DDS_ReadCondition_get_trigger_value (inherited) . . . . . . . . . . . . . . . . 5283.5.7.5 DDS_ReadCondition_get_view_state_mask . . . . . . . . . . . . . . . . . . . . . . 5283.5.8 Class DDS_QueryCondition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5293.5.8.1 DDS_QueryCondition_get_datareader (inherited) . . . . . . . . . . . . . . . . . . 5303.5.8.2 DDS_QueryCondition_get_instance_state_mask (inherited). . . . . . . . . . 530

xviiC Reference Guide

Table of Contents

3.5.8.3 DDS_QueryCondition_get_query_parameters. . . . . . . . . . . . . . . . . . . . . 5313.5.8.4 DDS_QueryCondition_get_query_expression . . . . . . . . . . . . . . . . . . . . . 5323.5.8.5 DDS_QueryCondition_get_sample_state_mask (inherited) . . . . . . . . . . 5323.5.8.6 DDS_QueryCondition_get_trigger_value (inherited) . . . . . . . . . . . . . . . 5333.5.8.7 DDS_QueryCondition_get_view_state_mask (inherited) . . . . . . . . . . . . 5333.5.8.8 DDS_QueryCondition_set_query_parameters . . . . . . . . . . . . . . . . . . . . . 5333.5.9 Class DDS_DataReaderView (abstract) . . . . . . . . . . . . . . . . . . . . . . . . . . . 5343.5.9.1 DDS_DataReaderView_create_querycondition. . . . . . . . . . . . . . . . . . . . 5403.5.9.2 DDS_DataReaderView_create_readcondition . . . . . . . . . . . . . . . . . . . . . 5403.5.9.3 DDS_DataReaderView_delete_contained_entities . . . . . . . . . . . . . . . . . 5413.5.9.4 DDS_DataReaderView_delete_readcondition . . . . . . . . . . . . . . . . . . . . . 5413.5.9.5 DDS_DataReaderView_enable (inherited) . . . . . . . . . . . . . . . . . . . . . . . 5413.5.9.6 DDS_DataReaderView_get_datareader . . . . . . . . . . . . . . . . . . . . . . . . . . 5423.5.9.7 DDS_DataReaderView_get_key_value (abstract) . . . . . . . . . . . . . . . . . . 5423.5.9.8 DDS_DataReaderView_get_qos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5433.5.9.9 DDS_DataReaderView_get_status_changes (inherited) . . . . . . . . . . . . . 5443.5.9.10 DDS_DataReaderView_get_statuscondition (inherited) . . . . . . . . . . . . 5443.5.9.11 DDS_DataReaderView_lookup_instance (abstract) . . . . . . . . . . . . . . . 5443.5.9.12 DDS_DataReaderView_read (abstract) . . . . . . . . . . . . . . . . . . . . . . . . . 5453.5.9.13 DDS_DataReaderView_read_instance (abstract). . . . . . . . . . . . . . . . . . 5453.5.9.14 DDS_DataReaderView_read_next_instance (abstract) . . . . . . . . . . . . . 5453.5.9.15 DDS_DataReaderView_read_next_instance_w_condition (abstract) . . 5463.5.9.16 DDS_DataReaderView_read_next_sample (abstract) . . . . . . . . . . . . . . 5463.5.9.17 DDS_DataReaderView_read_w_condition (abstract) . . . . . . . . . . . . . . 5473.5.9.18 DDS_DataReaderView_return_loan (abstract) . . . . . . . . . . . . . . . . . . . 5473.5.9.19 DDS_DataReaderView_set_qos. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5483.5.9.20 DDS_DataReaderView_take (abstract) . . . . . . . . . . . . . . . . . . . . . . . . . 5493.5.9.21 DDS_DataReaderView_take_instance (abstract). . . . . . . . . . . . . . . . . . 5493.5.9.22 DDS_DataReaderView_take_next_instance (abstract) . . . . . . . . . . . . . 5503.5.9.23 DDS_DataReaderView_take_next_instance_w_condition (abstract) . . 5503.5.9.24 DDS_DataReaderView_take_next_sample (abstract) . . . . . . . . . . . . . . 5513.5.9.25 DDS_DataReaderView_take_w_condition (abstract) . . . . . . . . . . . . . . 5513.5.10 Class SPACE_FooDataReaderView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5523.5.10.1 SPACE_FooDataReaderView_create_querycondition (inherited) . . . . 5563.5.10.2 SPACE_FooDataReaderView_create_readcondition (inherited). . . . . . 5563.5.10.3 SPACE_FooDataReaderView_delete_contained_entities . . . . . . . . . . . 5573.5.10.4 SPACE_FooDataReaderView_delete_readcondition (inherited). . . . . . 5573.5.10.5 SPACE_FooDataReaderView_enable (inherited) . . . . . . . . . . . . . . . . . 5573.5.10.6 SPACE_FooDataReaderView_get_datareader (inherited). . . . . . . . . . . 5573.5.10.7 SPACE_FooDataReaderView_get_key_value. . . . . . . . . . . . . . . . . . . . 5583.5.10.8 SPACE_FooDataReaderView_get_qos (inherited) . . . . . . . . . . . . . . . . 5583.5.10.9 SPACE_FooDataReaderView_get_status_changes (inherited) . . . . . . . 558

xviiiC Reference Guide

Table of Contents

3.5.10.10 SPACE_FooDataReaderView_get_statuscondition (inherited) . . . . . . 5583.5.10.11 SPACE_FooDataReaderView_lookup_instance . . . . . . . . . . . . . . . . . 5593.5.10.12 SPACE_FooDataReaderView_read . . . . . . . . . . . . . . . . . . . . . . . . . . . 5593.5.10.13 SPACE_FooDataReaderView_read_instance . . . . . . . . . . . . . . . . . . . 5593.5.10.14 SPACE_FooDataReaderView_read_next_instance . . . . . . . . . . . . . . . 5603.5.10.15 SPACE_FooDataReaderView_read_next_instance_w_condition . . . . 5603.5.10.16 SPACE_FooDataReaderView_read_next_sample . . . . . . . . . . . . . . . . 5613.5.10.17 SPACE_FooDataReaderView_read_w_condition . . . . . . . . . . . . . . . . 5613.5.10.18 SPACE_FooDataReaderView_return_loan . . . . . . . . . . . . . . . . . . . . . 5613.5.10.19 SPACE_FooDataReaderView_set_qos (inherited) . . . . . . . . . . . . . . . 5623.5.10.20 SPACE_FooDataReaderView_take . . . . . . . . . . . . . . . . . . . . . . . . . . . 5623.5.10.21 SPACE_FooDataReaderView_take_instance . . . . . . . . . . . . . . . . . . . 5633.5.10.22 SPACE_FooDataReaderView_take_next_instance . . . . . . . . . . . . . . . 5633.5.10.23 SPACE_FooDataReaderView_take_next_instance_w_condition . . . . 5643.5.10.24 SPACE_FooDataReaderView_take_next_sample . . . . . . . . . . . . . . . . 5643.5.10.25 SPACE_FooDataReaderView_take_w_condition . . . . . . . . . . . . . . . . 5643.6 QosProvider. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5653.6.1 Class DDS_QosProvider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5653.6.1.1 DDS_QosProvider__alloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5663.6.1.2 DDS_QosProvider_get_participant_qos. . . . . . . . . . . . . . . . . . . . . . . . . . 5673.6.1.3 DDS_QosProvider_get_topic_qos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5683.6.1.4 DDS_QosProvider_get_subscriber_qos . . . . . . . . . . . . . . . . . . . . . . . . . . 5693.6.1.5 DDS_QosProvider_get_datareader_qos . . . . . . . . . . . . . . . . . . . . . . . . . . 5703.6.1.6 DDS_QosProvider_get_publisher_qos. . . . . . . . . . . . . . . . . . . . . . . . . . . 5713.6.1.7 DDS_QosProvider_get_datawriter_qos . . . . . . . . . . . . . . . . . . . . . . . . . . 572

Appendix A Quality Of Service 577Affected Entities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577Basic Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577DDS_DataReaderQos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579DDS_DataWriterQos. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582DDS_DomainParticipantFactoryQos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585DDS_DomainParticipantQos. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586DDS_PublisherQos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588DDS_SubscriberQos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589DDS_TopicQos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590

Appendix B API Constants and Types 595

Appendix C Platform Specific IDL Interface 599dds_dcps.idl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599

xixC Reference Guide

Table of Contents

Appendix D SampleStates, ViewStates and InstanceStates 629SampleInfo Class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629sample_state. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629instance_state. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631view_state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632State Masks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634Operations Concerning States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635

Appendix E Class Inheritance 639

Appendix F Listeners, Conditions and Waitsets 641Communication Status Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643Listeners. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646Conditions and Waitsets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647DDS_StatusCondition Trigger State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651DDS_ReadCondition and DDS_QueryCondition Trigger State . . . . . . . . . . . . . . 651DDS_GuardCondition Trigger State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652

Appendix G DDS_Topic Definitions 653DDS_Topic Definition Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653Complex Topics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654IDL Pre-processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654

Appendix H DCPS Queries and Filters 659SQL Grammar in BNF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659SQL Token Expression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660SQL Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661

Appendix I Built-in Topics 663

Bibliography 673

Glossary 677

Index 681

xxC Reference Guide

List of FiguresFigure 1: C Reference Guide Document Structure . . . . . . . . . . . . . . . . . . . . . . 3Figure 2: DCPS Module Composition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Figure 3: DCPS Infrastructure Module’s Class Model . . . . . . . . . . . . . . . . . . 42Figure 4: DCPS Domain Module’s Class Model . . . . . . . . . . . . . . . . . . . . . . . . 44Figure 5: DCPS Topic-Definition Module’s Class Model . . . . . . . . . . . . . . . . 45Figure 6: Data Type “Foo” Typed Classes Pre-processor Generation . . . . . . 46Figure 7: DCPS Publication Module’s Class Model . . . . . . . . . . . . . . . . . . . . . 47Figure 8: DCPS Subscription Module’s Class Model . . . . . . . . . . . . . . . . . . . 48Figure 9: DCPS Infrastructure Module’s Class Model . . . . . . . . . . . . . . . . . . 52Figure 10: QosPolicy Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Figure 11: DCPS Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Figure 12: DCPS DDS_Status Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Figure 13: DCPS DDS_WaitSets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Figure 14: DCPS DDS_Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Figure 15: DCPS Domain Module’s Class Model . . . . . . . . . . . . . . . . . . . . . . 161Figure 16: DCPS Topic-Definition Module Class Model . . . . . . . . . . . . . . . . 254Figure 17: Pre-processor Generation of the Typed Classes for Data Type “Foo” . . . . . . . . . . . . . . . . . . . . . . . . 255Figure 18: The DCPS Publication Module’s Class Model . . . . . . . . . . . . . . . 289Figure 19: The DCPS Subscription Module’s Class Model . . . . . . . . . . . . . . 391Figure 20: State Chart of the sample_state for a Single Sample . . . . . . . . . . 630Figure 21: State Chart of the instance_state for a Single Instance . . . . . . . . 632Figure 22: State Chart of the view_state for a Single Instance . . . . . . . . . . . 633Figure 23: DCPS Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639Figure 24: Plain Communication Status State Chart . . . . . . . . . . . . . . . . . . . 644Figure 25: Read Communication Status DDS_DataReader Statecraft . . . . 645Figure 26: DDS_Subscriber Statecraft for a Read Communication Status . 646Figure 27: DCPS Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647Figure 28: DCPS DDS_WaitSets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648Figure 29: DCPS DDS_Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650Figure 30: Blocking Behaviour of a Waitset State Chart . . . . . . . . . . . . . . . 651

xxiC Reference Guide

List of Figures

xxiiC Reference Guide

PrefaceAbout the C Reference Guide

The C Reference Guide provides a detailed explanation of the OpenSplice(Subscription Paradigm for the Logical Interconnection of Concurrent Engines)Application Programming Interfaces for the C language.This reference guide is based on the OMG’s Data Distribution Service Specificationand C Language Mapping Specification. The C Reference Guide describes the Data Centric Publish Subscribe (DCPS) layer.The purpose of the DCPS is the distribution of data (publish/subscribe). Thestructure of the DCPS is divided into five modules. Each module consists of severalclasses, which in turn generally contain several operations.

Intended AudienceThe C Reference Guide is intended to be used by C programmers who are usingOpenSplice to develop applications.

OrganisationThe C Reference Guide is organised into the following topics.The Introduction describes the details of the document structure.Chapter 1, DCPS API General Description, is a general description of the DCPSAPI and its error codes.Chapter 2, DCPS Modules, provides the detailed description of the DCPS modules.Chapter 3, DCPS Classes and Operations, provides the detailed description of theDCPS classes, structs and operations.The following appendices are included, as well as a Bibliography containingreferences material and Glossary:Appendix A, Quality Of ServiceAppendix B, API Constants and TypesAppendix C, Platform Specific IDL InterfaceAppendix D, SampleStates, ViewStates and InstanceStatesAppendix E, Class InheritanceAppendix F, Listeners, Conditions and WaitsetsAppendix G, DDS_Topic DefinitionsAppendix H, DCPS Queries and FiltersAppendix I, Built-in Topics

xxiiiC Reference Guide

Preface

ConventionsThe conventions listed below are used to guide and assist the reader inunderstanding the C Reference Guide.Item of special significance or where caution needs to be taken.Item contains helpful hint or special information.Information applies to Windows (e.g. XP, 2003, Windows 7) only.Information applies to Unix based systems (e.g. Solaris) only.C language specificC++ language specificC# language specific.Java language specificHypertext links are shown as blue italic underlined.On-Line (PDF) versions of this document: Items shown as cross-references, e.g.Contacts on page xxv, are hypertext links: click on the reference to go to the item.

Courier fonts indicate programming code and file names.Extended code fragments are shown in shaded boxes:

Italics and Italic Bold are used to indicate new terms, or emphasise an item.Sans-serif and Sans-serif Bold are used to indicate elements of a Graphical UserInterface (GUI) or Integrated Development Environment (IDE), such as anOK button, and sequences of actions, such as selecting File > Save from a menu.

Step 1: One of several steps required to complete a task.

% Commands or input which the user enters on thecommand line of the computer terminal

NameComponent newName[] = new NameComponent[1]; // set id field to “example” and kind field to an empty string newName[0] = new NameComponent (“example”, ““);

iWIN

UNIX

CC++ C#Java

xxivC Reference Guide

Preface

ContactsADLINK can be reached at the following contact points for information andtechnical support.

Web: http://ist.adlinktech.comE-mail: ist_info@adlinktech.com

USA Corporate Headquarters European Head OfficeADLINK Technology Corporation400 TradeCenterSuite 5900Woburn, MA01801USA

Tel: +1 781 569 5819

ADLINK Technology LimitedThe Edge5th Avenue, Team ValleyGatesheadNE11 0XAUK

Tel: +44 (0)191 497 9900

xxvC Reference Guide

Preface

xxviC Reference Guide

INTRODUCTION

About the C Reference GuideDocument Structure

The C Reference Guide document structure is based on the structure of the DCPSPlatform Independent Model (DCPS PIM) of the Data Distribution ServiceSpecification. The detailed description is subdivided into the PIM Modules, whichare then subdivided into classes. Some of the classes are implemented as structs in the DCPS Platform SpecificModel (DCPS PSM) of the Data Distribution Service Specification, as indicated inthe Interface Description Language (IDL) chapter of the PSM (see Appendix C,Platform Specific IDL Interface). These structs are described in the respectivechapters. • In the classes as described in the PIM, which are implemented as a class in the

PSM, the operations are described in detail. • In the classes as described in the PIM, which are implemented as a struct in the

PSM, the struct contents are described in detail. • The order of the modules and classes is conform the PIM part. • The order of the operations or struct contents is alphabetical. • Each description of a class or struct starts with the API description header file.

Figure 1: C Reference Guide Document Structure

Modules . . .

DDS-DCPS

Classes . . .

Operations . . .

Structs . . .

detailed description

3C Reference Guide

Introduction

OperationsSeveral types of operations are described in this manual. The different types ofoperations are: basic, inherited, abstract and abstract interface. All operations of anytype can be found in their respective class. The details of their description dependson the type of operation.Basic operations are described in detail in the class they are implemented in.• Inherited operations only refer to the operation in the class they are inherited

from. The detailed description is not repeated.• Abstract operations only refer to the type specific implementations in their

respective derived class. The detailed description is not repeated.• Abstract operations which are implemented as an interface (Listeners), are

described in detail in their class. These operations must be implemented in theapplication.

In the API description header file, the inherited and abstract operations arecommented out since they are not implemented in this class.Inheritance in the C API is implemented by prefixing the name of the operation withDDS_ and the name of the class they are in. For example, the operation get_namein the class Topic is named DDS_Topic_get_name. Since this operation isactually inherited from the class TopicDescription the operation refers to theTopicDescription c l a s s fo r more in fo rmat ion . However, i n theTopicDescription c l a s s t h i s o p e r a t i o n i s n a m e dDDS_TopicDescripton_get_name.

4C Reference Guide

API REFERENCE

CHAPTER

1 DCPS API General Description The structure of the DCPS is divided into modules, which are described in detail inthe next chapter. Each module consists of several classes, which in turn may containseveral operations.S o m e o f t h e s e o p e ra t i o n s h a v e a n o p e r a t i o n r e t u r n c o d e o f t y p eDDS_ReturnCode_t, which is defined in the next table:

Table 1: Return Codes

DDS_ReturnCode_t Return Code DescriptionDDS_RETCODE_OK Successful returnDDS_RETCODE_ERROR Generic, unspecified errorDDS_RETCODE_BAD_PARAMETER Illegal parameter valueDDS_RETCODE_UNSUPPORTED Unsupported operation or DDS_QosPolicy setting. Can

only be returned by operations that are optional oro p e r a t i o n s t h a t u s e s a n o p t i o n a lDDS_<DDS_Entity>QoS as a parameter

DDS_RETCODE_ALREADY_DELETED The object target of this operation has already been deletedDDS_RETCODE_OUT_OF_RESOURCES Service ran out of the resources needed to complete the

operationDDS_RETCODE_NOT_ENABLED Operation invoked on an DDS_Entity that is not yet

enabledDDS_RETCODE_IMMUTABLE_POLICY Appl i ca t ion a t t empted to mod i fy an immutab le

DDS_QosPolicy

DDS_RETCODE_INCONSISTENT_POLICY Application specified a set of policies that are not consistentwith each other

DDS_RETCODE_PRECONDITION_NOT_MET A pre-condition for the operation was not met

7 API Reference

1 DCPS API General Description 1.1 Thread Safety

The name scope (name space) of these return codes is DDS. The operation returncodes DDS_RETCODE_OK , DDS_RETCODE_ERROR , DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_UNSUPPORTED and DDS_RETCODE_ALREADY_DELETED are default for operationsthat return an operation return code and are therefore not explicitly mentioned in theDDS specification. However, in this manual they are mentioned along with eachoperation.Some operations are not implemented. These operations are mentioned includingt h e i r s y n o p s i s , b u t n o t d e s c r ib e d in t h i s m a n u a l a n d r e t u r nDDS_RETCODE_UNSUPPORTED when called from the application. All constants andtypes are given in Appendix B, API Constants and Types.

1.1 Thread SafetyA l l o p e r a t i o n s a r e t h r e a d s a f e a p a r t f r o m t h eDDS_DomainParticipantFactory_get_instance operation. It is theapplications responsibility to call DDS_DomainParticipantFactory_get_instance only from one application thread. This restriction only applies tothe first call of DDS_DomainParticipantFactory_get_instance.

1.2 Signal HandlingEvery application that participates in a domain should register signal-handlers inorder to protect the data distribution service in case of an exception or terminationreques t . This i s done au tomat ica l ly when the appl ica t ion ca l l s theDDS_DomainParticipantFactory_get_instance operation. The datadistribution service distinguishes between two kinds of signals: synchronous (i.e.exceptions) and asynchronous signals (i.e. termination requests).

DDS_RETCODE_TIMEOUT The operation timed outDDS_RETCODE_ILLEGAL_OPERATION An operation was invoked on an inappropriate object or at

an inappropriate time (as determined by QosPolicies thatcontrol the behaviour of the object in question). There is noprecondition that could be changed to make the operationsucceed.

DDS_RETCODE_NO_DATA Indicates a situation where the operation did not return anydata

Table 1: Return Codes

DDS_ReturnCode_t Return Code Description

UNIX

8API Reference

1 DCPS API General Description 1.3 Memory Management

1.2.1 Synchronous SignalsThe data distribution service registers a signal-handler for the followingsynchronous signals: SIGILL, SIGTRAP, SIGABRT, SIGFPE, SIGBUS, SIGSEGVand SIGSYS. If a signal-handler is already registered for any of these signals it willbe chained by the handlers registered by the data distribution service. Uponreceiving any of the mentioned signals, the signal-handler will synchronouslydetach the application from the domain and call any chained handler if available.This allows core dumps to be created when an error occurs in application-code,without sacrificing the integrity of the data distribution service. Because the signalis processed synchronously, the offending thread will not be able to continue. Synchronous signals can also be received asynchronously from another process (i.e.'kill -ABRT <pid>'). This is handled by the signal-handlers registered by thedata distribution service and the behaviour will mimic the behaviour of a regularsynchronous signal, occurring at the point in the application when the signal isreceived. A log message will be recorded stating that an asynchronously receivedsynchronous signal occurred, including the source of the signal.

1.2.2 Asynchronous SignalsThe asynchronous signal-handlers are only registered by the data distributionservice if the application did not already register a handler, nor set the ignore-flagfor these signals. If the data distribution service handlers are registered, the defaulthandlers are chained. The signels that are handled are: SIGINT, SIGQUIT,SIGTERM, SIGHUP and SIGPIPE. When receiving any of these signals, the handlersof the data distribution service will ensure a disconnection from the domain. Thedefault handler will in turn cause the application to terminate immediately.

1.3 Memory ManagementWhen objects are being created, they occupy memory space. To avoid memory leakswhen they are not used any more, these objects have to be deleted in order to releasethe memory space. However, when using pointers, it is difficult to keep track ofwhich object has been released and which has not. When objects are not beingreleased, the memory leak finally uses up all the resources and the application fails.On the other hand, when an object is being released twice because there were twopointers to the same object, the application fails. This implementation is based onthe OMG C Language Mapping Specification. Accordingly, the CORBA rules listedbelow apply.

1.3.1 IDL Mapping Rules for SequencesThe names of the operations and types are given by the IDL mapping rules. Forsequences several rules apply. The basic IDL definition of a sequence is defined by:

9API Reference

1 DCPS API General Description 1.3 Memory Management

module name-space {typedef sequence<<sequence-element-type>>

<sequence-name>;}

In the C language, this results in the following type definition of the sequence:typedef

DDS_sequence_<name-space-prefix><sequence-element-type><name-space>_<sequence-name>

In this type definition, the <sequence-element-type> is the type of the objectsin the sequence. This <sequence-element-type> may be a standard type or aData Distribution Service defined type. The <name-space-prefix> representsthe name space in which the <sequence-element-type> is defined. Thestandard types have an empty prefix. In the Data Distribution Service all thetypedefs are set within the module DDS block, therefore defined types have theprefix DDS_. Finally, the <sequence-name> is name of the sequence and isalways prefixed by DDS_.

1.3.1.1 Standard Defined TypeThe standard defined types are the types as defined in the Data Distribution Servicespecification. For example, for the standard defined <sequence-element-type>of type string with a <sequence-name> of StringSeq, the following IDLdefinition is given:

typedef sequence<string> StringSeq

In C, this results in the following type definition of the sequence:typedef DDS_sequence_string DDS_StringSeq

1.3.1.2 User-Defined TypeThe user-defined types are the types as defined in the application. For example, forthe user-def ined <sequence-element-type> o f type Foo wi th a<sequence-name> of name FooSeq in the module SPACE, the following IDLdefinition is given:

module SPACE {typedef sequence<Foo> FooSeq;

}

In C, this results in the following type definition of the sequence:typedef DDS_sequence_SPACE_Foo SPACE_FooSeq

10API Reference

1 DCPS API General Description 1.3 Memory Management

1.3.1.3 Data Distribution Service Defined TypeF o r e x a m p l e , f o r t h e D a t a D i s t r i bu t i on Se rv i ce de f i ne d<sequence-element-type> of type SampleInfo with a <sequence-name> ofname SampleInfoSeq, the following IDL definition is given:

typedef sequence<SampleInfo> SampleInfoSeq

In C, this results in the following type definition of the sequence:typedef DDS_sequence_DDS_SampleInfo DDS_SampleInfoSeq

1.3.2 Plain SequencesThe following table shows the sequences for which the resources have to bemanaged. In other words, for these sequences DDS_<sequence-name>__allocand DDS_<sequence-name>_allocbuf operations are available. For sequences,which are only used as an out parameter, the application does not need to use theseallocation operations, since the Data Distribution Service allocates them. In thiscase, the application may use these operations for its own sequences. Furthermore tofree the resources allocated with DDS_<sequence-name>__alloc andDDS_<sequence-name>_allocbuf the application must use the DDS_freeoperation. It does not make any difference whether the application or the DataDistribution Service does the allocation. When the application does not use theDDS_free operation, the application will fail. The DDS_free operation operatesrecursively, in other words all embedded structures are released.Sequences and buffers can also be allocated on stack. However in case theapplication allocates a sequence or buffer on stack, the DDS_free operation maynot be used on this object, otherwise the application will fail.

Table 2: Sequences

Sequence Name Parameter TypeIn Out Inout Return

DDS_ConditionSeq xDDS_StringSeq x xDDS_DataReaderSeq xDDS_InstanceHandleSeq xDDS_QosPolicyCountSeq Used in status struct only.DDS_SampleInfoSeq xDDS_sequence_octet Used in QosPolicy struct only.

11API Reference

1 DCPS API General Description 1.3 Memory Management

1.3.3 Sequences Embedded in QosPolicy ObjectsThe following table shows the QosPolicy objects for which the resources have tobe managed because they contain sequences. In other words, for these QosPolicyobjects DDS_<QosPolicy>__alloc operations are available. The buffers used inthe se QosPolicy o b j e c t s m u s t b e a l l o c a t e d u s i n g t h eDDS_<sequence-name>_allocbuf operations. The DDS_free operation takescare of the embedded sequences and the buffers in a QosPolicy.

1.3.4 Sequences Embedded in Status ObjectsThe following table shows the Status objects for which the resources have to bemanaged because they contain sequences. In other words, for these Status objectsDDS_<Status>__alloc operations are available. The buffers used in theseStatus objects must be allocated using the DDS_<sequence-name>_allocbufoperations. The DDS_free operation takes care of the embedded sequences and thebuffers in a Status.

1.3.5 Resources and operationsThe interface description of the memory management operations is as follows:/* interface Memory management */

typedef struct {

Table 3: QosPolicy Objects

QosPolicy Name Parameter Type ContainsSequenceIn Out Inout Return

DDS_DomainParticipantQos x x DDS_sequence_octet

DDS_TopicQos x x DDS_sequence_octet

DDS_PublisherQos x x DDS_sequence_octet

DDS_StringSeq

DDS_DataWriterQos x x DDS_sequence_octet

DDS_SubscriberQos x x DDS_sequence_octet

DDS_StringSeq

DDS_DataReaderQos x x DDS_sequence_octet

Table 4: Status Objects

Status Name Parameter Type ContainsSequenceIn Out Inout Return

DDS_OfferedIncompatibleQosStatus x x DDS_QosPolicyCountSeq

DDS_RequestedIncompatibleQosStatus x x DDS_QosPolicyCountSeq

12API Reference

1 DCPS API General Description 1.3 Memory Management

DDS_unsigned_long _maximum; DDS_unsigned_long _length; DDS_<sequence-element-type> *_buffer; DDS_boolean _release;} DDS_sequence_<name-space-prefix><sequence-element-type>;typedef

DDS_sequence_<name-space-prefix><sequence-element-type>DDS_<sequence-name>

/* implemented API operations */void DDS_sequence_set_release (void *sequence, DDS_boolean release);DDS_boolean DDS_sequence_get_release (void *sequence);DDS_<sequence-name> * DDS_<sequence-name>__alloc (void);DDS_<sequence-element-type> * DDS_<sequence-name>_allocbuf (DDS_unsigned_long len);DDS_<QosPolicy> DDS_<QosPolicy>__alloc (void);DDS_<Status> DDS_<Status>__alloc (void);void DDS_free (void *);

The following paragraphs describe the usage of all memory managementoperations.

1.3.5.1 Sequences DDS_<sequence-name>

Synopsis#include <dds_dcps.h>

typedef struct { DDS_unsigned_long _maximum; DDS_unsigned_long _length; DDS_<sequence-element-type> *_buffer; DDS_boolean _release;

13API Reference

1 DCPS API General Description 1.3 Memory Management

} DDS_sequence_<name-space-prefix> <sequence-element-type>;

typedef DDS_sequence_<name-space-prefix><sequence-element-type> DDS_<sequence-name>

DescriptionThe typedef DDS_<sequence-name> represents the sequence which contains theobjects of <sequence-element-type>.

AttributesDDS_unsigned_long _maximum - the maximum number of elements that can be

contained in the sequence.DDS_unsigned_long _length - the actual number of elements in the sequence.DDS_<sequence-element-type> *_buffer - a pointer to the sequence buffer.DDS_boolean _release - indicates whether this sequence owns the memory of

_buffer.

Detailed DescriptionThe typedef DDS_<sequence-name> represents the sequence struct that holds thesequence attributes associated with the sequence buffer, which contains the objectsof <sequence-element-type> . This sequence is allocated by callingDDS_<sequence-name>__alloc. The sequence buffer must be allocatedseparately by calling DDS_<sequence-name>_allocbuf. In other words whenusing a sequence, the memory space must be allocated for both the sequence structand the sequence buffer. Whether, the application must allocate the resources or theData Distribution Service allocates the resources, depends on the type of usage.

In or Inout ParameterIn case the sequence is passed as an in or inout parameter, both the sequence and thebuffer must be allocated by the application. The application must set the attributesof the sequence according to the size and ownership of the buffer. Furthermore, foran inout parameter the application can control whether the Data Distribution Servicemust replace the elements in the sequence, the application can allow this by settingthe _release attribute.• When set to TRUE the Data Distribution Service is allowed to free any pointer

types. The Data Distribution Service sets the _length attribute to the number ofreturned elements. The number of elements never exceeds the number set by theapplication in the _maximum attribute.

14API Reference

1 DCPS API General Description 1.3 Memory Management

• When set to FALSE the Data Distribution Service is not allowed to free the pointertypes. In this case, the Data Distribution Service allocates exactly the amount ofelements and set the _length and the _maximum attributes of the sequence tothat amount.

• In either case, the sequence and the buffer must be released by the application bycalling DDS_free on the sequence. In this case also the buffer is released, sincethe DDS_free operation is recursive.

Out or Return ParameterIn case the sequence is used as an out parameter or a sequence is returned by afunction, both the sequence and the buffer are allocated by the Data DistributionService. The attributes of the sequence are set by the Data Distribution Serviceaccording to the size and ownership of the buffer. The sequence and the buffer mustbe released by the application by calling DDS_free on the sequence. In this casealso the buffer is released, since the DDS_free operation is recursive.In case the Data Distribution Service has no data to return, it returns an emptysequence with the _length and the _maximum attributes of the sequence set tozero, the _buffer attribute set to DDS_OBJECT_NIL and the _release attributeset to FALSE.

Allocation on the StackIn case the sequence is allocated by the application. The application may alsoallocate the sequence on stack for performance reason instead of callingDDS_<sequence-name>__alloc. When the buffer is allocated on the stack theapplication must also set the _release attribute to FALSE as described below. In casethe buffer is allocated using DDS_<sequence-name>_allocbuf then theapplication must release the buffer separately by calling DDS_free on _buffer ofthe sequence.

AttributesThe attributes of the DDS_<sequence-name> struct must be set after allocation. Incase of an out parameter or the sequence is returned by a function, the attributes areset by the Data Distribution Service. In case of an in parameter or inout parameter,the attributes must be set by the application.The _length attribute of the sequence must be set to the current length of thesequence. In other words equal to the number of valid sequence elements.The _maximum attribute of the sequence must be set to the size of the allocatedsequence buffer. In other words equal to the len parameter used in the call toDDS_<sequence-element-type>_allocbuf.

15API Reference

1 DCPS API General Description 1.3 Memory Management

The _buffer attribute of the sequence must be set to the pointer to the allocatedsequence buffer. In other words equal to the returned pointer from the call toDDS_<sequence-element-type>_allocbuf. Or in case of allocation on stack,the pointer to the variable.The _release flag of the sequence may not be set directly. The _release flag ofthe sequence must be set by using DDS_sequence_set_release and may only beread by using DDS_sequence_get_release. DDS_sequence_set_releasemay only be used by the creator of the sequence. If it is not called for a givensequence instance, then the default value of the _release flag for that instance isFALSE.If the _release flag of the sequence is set to TRUE, the sequence effectively“owns” the resource pointed to by _buffer; if the flag is set to FALSE, theapplication is responsible for the resource. If, for example, a sequence is returnedfrom an operation with its release flag set to FALSE, calling DDS_free on thereturned sequence pointer does not deallocate the memory pointed to by _buffer.Before calling DDS_free on the _buffer member of a sequence directly, thea p p l i c a t i o n s h o u l d c h e ck t h e _release f l a g u s i n gDDS_sequence_get_release. If it returns FALSE, the application should notinvoke DDS_free on the _buffer member; doing so produces undefinedbehaviour.

1.3.5.2 DDS_sequence_set_release

Synopsis#include <dds_dcps.h>void

DDS_sequence_set_release (void *sequence, DDS_boolean release);

DescriptionThis operation sets the state of the _release flag of the sequence.

Parametersin void *sequence - a pointer to the DDS_<sequence-name>.in DDS_boolean release - the new state of the _release flag of the

sequence.

Return Value<none>

16API Reference

1 DCPS API General Description 1.3 Memory Management

Detailed DescriptionThis operation sets the state of the _release flag of the sequence. If the flag is setto TRUE, the sequence effectively “owns” the resource pointed to by _buffer; ifthe flag is set to FALSE, the application is responsible for the resource. If, forexample, a sequence is returned from an operation with its release flag set to FALSE,calling DDS_free on the returned sequence pointer does not deallocate the memorypointed to by _buffer. Passing a DDS_OBJECT_NIL pointer or a pointer tosomething other than a sequence type to DDS_sequence_set_release producesundefined behaviour.DDS_sequence_set_release should only be used by the creator of the sequence.If it is not called for a given sequence instance, then the default value of the_release flag for that instance is FALSE. The _release flag of the sequence maynot be set directly. It may only be changed by this operation.

1.3.5.2.1 DDS_sequence_get_release

Synopsis#include <dds_dcps.h>DDS_boolean DDS_sequence_get_release (void *sequence);

DescriptionThis operation gets the state of the _release flag of the sequence.

Parametersin void *sequence - a pointer to the DDS_<sequence-name>.

Return ValueDDS_boolean - the present state of the _release flag of the sequence.

Detailed DescriptionThis operation gets the present state of the _release flag of the sequence. If theflag returned is TRUE, the sequence effectively “owns” the resource pointed to by_buffer; if the flag returned is FALSE, the application is responsible for theresource. If, for example, a sequence is returned from an operation with its releaseflag set to FALSE, calling DDS_free on the returned sequence pointer does notdeallocate the memory pointed to by _buffer. Before calling DDS_free on the_buffer member of a sequence directly, the application should check the_release flag using DDS_sequence_get_release. If it returns FALSE, theapplication should not invoke DDS_free on the _buffer member; doing so

17API Reference

1 DCPS API General Description 1.3 Memory Management

produces undefined behaviour. Passing a DDS_OBJECT_NIL pointer or a pointer tosomething other than a sequence type to DDS_sequence_get_release producesundefined behaviour.

1.3.5.2.2 DDS_<sequence-name>__alloc

Synopsis#include <dds_dcps.h>DDS_<sequence-name> DDS_<sequence-name>__alloc (void);

DescriptionThis operation allocates a new DDS_<sequence-name>.

Parameters<none>

Return ValueDDS_<sequence-name> - the po in te r to the newly-c rea ted empty

DDS_<sequence-name>. In case of an error, a DDS_OBJECT_NIL pointer isreturned.

Detailed DescriptionThis operation allocates a new empty DDS_<sequence-name>. This operationdoes not allocate the buffer and leave the sequence empty by setting the _lengthand _maximum attributes to zero and the _buffer attribute to DDS_OBJECT_NIL.The application may also allocate the DDS_<sequence-name> as a variable onstack. In this case the application may not use DDS_free on the sequence. In casethe DDS_<sequence-name> was allocated by this operation, and the applicationwants to release the DDS_<sequence-name> it must be released using DDS_freeon the sequence.I n c a s e t h e r e a r e i n s u ff i c i e n t r e s o u r c e s a v a i l a b l e t o a l l o c a t e t h eDDS_<sequence-name>, a DDS_OBJECT_NIL pointer is returned instead.

1.3.5.2.3 DDS_<sequence-element-type>_allocbuf

Synopsis#include <dds_dcps.h>

DDS_<sequence-element-type> * DDS_<sequence-name>_allocbuf (DDS_unsigned_long len);

18API Reference

1 DCPS API General Description 1.3 Memory Management

DescriptionThis operation allocates a new DDS_<sequence-element-type> buffer.

Parameters<none>

Return ValueDDS_<sequence-element-type> - the pointer to the newly-created buffer of

DDS_<sequence-element-type>. In case of an error, a DDS_OBJECT_NILpointer is returned.

Detailed DescriptionThis operation allocates a new buffer of DDS_<sequence-element-type>. Theapplication may also allocate the buffer of DDS_<sequence-element-type> as avariable on stack. In this case the application may not use DDS_free on the buffer.Furthermore, the application may only use DDS_free on the sequence when the_release flag of the sequence is set to FALSE and/or the _buffer pointer is set toDDS_OBJECT_NIL to prevent the buffer from being released. In case the buffer ofDDS_<sequence-element-type> was allocated by this operation, and theapplication wants to release the buffer of DDS_<sequence-element-type> itmust be released using DDS_free.In case there are insufficient resources available to allocate the buffer ofDDS_<sequence-element-type>, a DDS_OBJECT_NIL pointer is returnedinstead.

1.3.5.2.4 DDS_<QosPolicy>__alloc

Synopsis#include <dds_dcps.h>DDS_<QosPolicy> DDS_<QosPolicy>__alloc (void);

DescriptionThis operation allocates a new DDS_<QosPolicy>.

Parameters<none>

19API Reference

1 DCPS API General Description 1.3 Memory Management

Return ValueDDS_<QosPolicy> - the handle to the newly-created DDS_<QosPolicy>. In case of

an error, a DDS_OBJECT_NIL pointer is returned.

Detailed DescriptionThis operation allocates a new DDS_<QosPolicy>. The behaviour is identical toDDS_<sequence-name>__alloc except that it creates a QosPolicy structureincluding its embedded sequences. Further, the embedded buffers are not allocated.

1.3.5.2.5 DDS_<Status>__alloc

Synopsis#include <dds_dcps.h>DDS_<Status> DDS_<Status>__alloc (void);

DescriptionThis operation allocates a new DDS_<Status>.

Parameters<none>

Return ValueDDS_<Status> - the handle to the newly-created DDS_<Status>. In case of an

error, a DDS_OBJECT_NIL pointer is returned.

Detailed DescriptionThis operation allocates a new DDS_<Status>. The behaviour is identical toDDS_<sequence-name>__alloc except that it creates a Status structureincluding its embedded sequences. Further, the embedded buffers are not allocated.

1.3.5.2.6 DDS_string_alloc

Synopsis#include <dds_dcps.h>DDS_char * DDS_string_alloc (DDS_unsigned_long len);

DescriptionThis operation dynamically allocates a string of a specified length.

20API Reference

1 DCPS API General Description 1.3 Memory Management

Parametersin DDS_unsigned_long len - the length of the string to allocate. The allocated

string has length len+1 (1 character is allocated extra for the terminating NULcharacter).

Return ValueDDS_char * - the pointer to the allocated string. If there are insufficient resources

available, a DDS_OBJECT_NIL pointer is returned.

Detailed DescriptionThis operation dynamically allocates a string of a specified length. The allocatedstring has length len+1 (1 character is allocated extra for the terminating ‘0’character). If there are insufficient resources available, a DDS_OBJECT_NIL pointeris returned.A string that is allocated via DDS_string_alloc must be freed using the operationDDS_free.

1.3.5.2.7 DDS_free

Synopsis#include <dds_dcps.h>void DDS_free (void *);

DescriptionThis operation releases the allocated resources for the object in the parameter.

Parametersin void * - contains the object which resources should be released.

Return Value<none>

Detailed DescriptionThis operation releases the allocated resources for the object in the parameter. Theparameter may be a sequence in which case both the sequence and the sequencebuffer are released since this operation operates recursively. Or the parameter maybe a sequence buffer in case only the buffer is released. In both cases, theapplication is responsible to call this operation on the proper object in order torelease the resources.

21API Reference

1 DCPS API General Description 1.4 Listeners Interfaces

This operation may only be used when the resource was allocated using one of the_alloc operations. In case the object was declared as a variable on stack, theapplication may not use DDS_free on this object.This means that there are four combinations of allocation possible:B o t h t h e s e q u e n c e a n d t h e b u f f e r i s a l l o c a t e d u s i n g t h eDDS_<sequence-name>__alloc and DDS_<sequence-name>_allocbufoperation. In this case the DDS_free operation must be used on the sequence torelease both.• The sequence is allocated on stack and the buffer is allocated using theDDS_<sequence-name>_allocbuf operation. In this case the sequence maynot be released using the DDS_free operation but the buffer must be releasedusing the DDS_free operation (operated on the buffer).

• The sequence is allocated using the DDS_<sequence-name>__alloc operationand the buffer is allocated on stack. In this case the DDS_free operation must beused on the sequence but the buffer may not be released using the DDS_freeoperation. Since the DDS_free operation works recursively, the application mustput the _release flag of the sequence to FALSE and/or the _buffer pointer toDDS_OBJECT_NIL to prevent the buffer from being released.

• Both the sequence and the buffer are allocated on stack. In this case theDDS_free operation may not be used.

1.4 Listeners InterfacesThe Listener provides a generic mechanism (actually a callback function) for theData Distribution Service to notify the application of relevant asynchronous statuschange events, such as a missed deadline, violation of a DDS_QosPolicy setting,etc. The Listener is related to changes in communication status.The Listener interfaces are designed as an interface at PIM level. In other words,such an interface is part of the application which must implement the interfaceoperations. These operations must be provided by the application. All Listeneroperations must be implemented, it is up to the application whether an operation isempty or contains some functionality.Each DCPS DDS_Entity supports its own specialized kind of Listener.Therefore, the following Listeners are available:• DDS_DomainParticipantListener

• DDS_ExtDomainParticipantListener

• DDS_TopicListener

• DDS_ExtTopicListener

• DDS_PublisherListener

• DDS_DataWriterListener

22API Reference

1 DCPS API General Description 1.4 Listeners Interfaces

• DDS_SubscriberListener

• DDS_DataReaderListener

For example, since a DDS_DataReader is a kind of DDS_Entity, it has the abilityto have a Listener associated with it. In this case, the associated Listener mustbe of type DDS_DataReaderListener. This interface must be implemented by theapplication. All DDS_DataReaderListener operations must be implemented, it isup to the application whether an operation is empty or contains some functionality.As an example, one of the operations in the DDS_DataReaderListener is theDDS_DataReaderListener_on_liveliness_changed. This operation(implemented by the application) will be called by the Data Distribution Servicewhen the liveliness of the associated DDS_DataWriter has changed. In otherwords, it serves as a callback function to the event of a change in liveliness. Theparameters of the operation are supplied by the Data Distribution Service. In thisexample, the pointer to the DDS_DataReader and the status of the liveliness areprovided.

ImplementationThe struct DDS_<Entity>Listener represents the implementation of theListener for an <Entity>. Since a Listener is implemented as a struct ofpointers, the application must allocate this struct and initialise these pointers. TheListener is allocated using the appropriate DDS_<Entity>Listener__allocoperation. Each pointer must point to the appropriate callback operation defined inthe application (when the status is enabled). It is up to the application whether anoperation is empty or contains some functionality. An example is presented of theallocation and initialization of a DDS_DataReaderListener which is onlyenabled for the on_liveliness_changed. The on_liveliness_changedoperation is provided by the application:#include "dds_dcps.h"static struct DDS_DataReaderListener *msgListener;DDS_FooDataReader FooDR;/* at this point, it is not important how to create the FooDR */DataWriterListenerData UserDefined_ListenerData;/* at this point, it is not important how UserDefined_ListenerData is implemented. This parameter can be used for Listener identification. If not used, the parameter may be NULL. */ /* Prepare a listener for the Foo DataReader. */ msgListener = DDS_DataReaderListener__alloc(); msgListener.listener_data = UserDefined_ListenerData; msgListener.on_requested_deadline_missed = NULL; msgListener.on_requested_incompatible_qos = NULL;

23API Reference

1 DCPS API General Description 1.4 Listeners Interfaces

msgListener.on_sample_rejected = NULL; msgListener.on_liveliness_changed = (void (*)(void *, DDS_DataReader)) on_liveliness_changed; msgListener.on_data_available = NULL; msgListener.on_subscription_matched = NULL; msgListener.on_sample_lost = NULL; /* Set the Listener with a mask only to trigger on on_liveliness_changed. */ status = DDS_DataReader_set_listener (FooDR, &msgListener, DDS_LIVELINESS_CHANGED_STATUS);

1.4.1 Struct DDS_<Entity>ListenerThe struct DDS_<Entity>Listener represents the implementation of aListener.The interface description applies to the different types of <Entity>, that is theDomainParticipant, Topic, Publisher, DataWriter, Subscriber orDataReader. The actual attributes depends on the <Entity>. Only for theDomainParticipant all the fields are applicable. the description of these structsis as follows:struct DDS_DomainParticipantListener{

void *listener_data;DDS_DomainParticipantListener_InconsistentTopicListener

on_inconsistent_topic;DDS_DomainParticipantListener_OfferedDeadlineMissedListener

on_offered_deadline_missed;DDS_DomainParticipantListener_OfferedIncompatibleQosListener

on_offered_incompatible_qos;DDS_DomainParticipantListener_LivelinessLostListener

on_liveliness_lost;DDS_DomainParticipantListener_PublicationMatchListener

on_publication_matched;DDS_DomainParticipantListener_RequestedDeadlineMissedListener

on_requested_deadline_missed;DDS_DomainParticipantListener_ RequestedIncompatibleQosListener

on_requested_incompatible_qos;DDS_DomainParticipantListener_SampleRejectedListener

on_sample_rejected;DDS_DomainParticipantListener_LivelinessChangedListener

on_liveliness_changed;DDS_DomainParticipantListener_DataAvailableListener

on_data_available;

24API Reference

1 DCPS API General Description 1.4 Listeners Interfaces

DDS_DomainParticipantListener_SubscriptionMatchListeneron_subscription_matched;

DDS_DomainParticipantListener_SampleLostListeneron_sample_lost;

DDS_DomainParticipantListener_DataOnReadersListeneron_data_on_readers;

};

struct DDS_ExtDomainParticipantListener{

void *listener_data;DDS_ExtDomainParticipantListener_InconsistentTopicListener

on_inconsistent_topic;DDS_ExtDomainParticipantListener_AllDataDisposed

on_all_data_disposed;DDS_ExtDomainParticipantListener_OfferedDeadlineMissedListener

on_offered_deadline_missed;DDS_ExtDomainParticipantListener_OfferedIncompatibleQosListener

on_offered_incompatible_qos;DDS_ExtDomainParticipantListener_LivelinessLostListener

on_liveliness_lost;DDS_ExtDomainParticipantListener_PublicationMatchListener

on_publication_matched;DDS_ExtDomainParticipantListener_RequestedDeadlineMissedListener

on_requested_deadline_missed;DDS_ExtDomainParticipantListener_RequestedIncompatibleQosListener

on_requested_incompatible_qos;DDS_ExtDomainParticipantListener_SampleRejectedListener

on_sample_rejected;DDS_ExtDomainParticipantListener_LivelinessChangedListener

on_liveliness_changed;DDS_ExtDomainParticipantListener_DataAvailableListener

on_data_available;DDS_ExtDomainParticipantListener_SubscriptionMatchListener

on_subscription_matched;DDS_ExtDomainParticipantListener_SampleLostListener

on_sample_lost;DDS_ExtDomainParticipantListener_DataOnReadersListener

on_data_on_readers;}

struct DDS_TopicListener{

void *listener_data;DDS_TopicListener_InconsistentTopicListener

on_inconsistent_topic;};

struct DDS_ExtTopicListener{

25API Reference

1 DCPS API General Description 1.4 Listeners Interfaces

void *listener_data;DDS_ExtTopicListener_InconsistentTopicListener

on_inconsistent_topic;DDS_ExtTopicListener_AllDataDisposed on_all_data_disposed;

};

struct DDS_PublisherListener{

void *listener_data;DDS_PublisherListener_OfferedDeadlineMissedListener

on_offered_deadline_missed;DDS_PublisherListener_OfferedIncompatibleQosListener

on_offered_incompatible_qos;DDS_PublisherListener_LivelinessLostListener

on_liveliness_lost;DDS_PublisherListener_PublicationMatchListener

on_publication_matched;};struct DDS_DataWriterListener{

void *listener_data;DDS_DataWriterListener_OfferedDeadlineMissedListener

on_offered_deadline_missed;DDS_DataWriterListener_OfferedIncompatibleQosListener

on_offered_incompatible_qos;DDS_DataWriterListener_LivelinessLostListener

on_liveliness_lost;DDS_DataWriterListener_PublicationMatchListener

on_publication_matched;};struct DDS_SubscriberListener{

void *listener_data;DDS_SubscriberListener_RequestedDeadlineMissedListener

on_requested_deadline_missed;DDS_SubscriberListener_RequestedIncompatibleQosListener

on_requested_incompatible_qos;DDS_SubscriberListener_SampleRejectedListener

on_sample_rejected;DDS_SubscriberListener_LivelinessChangedListener

on_liveliness_changed;DDS_SubscriberListener_DataAvailableListener

on_data_available;DDS_SubscriberListener_SubscriptionMatchListener

on_subscription_matched;DDS_SubscriberListener_SampleLostListener

on_sample_lost;DDS_SubscriberListener_DataOnReadersListener

on_data_on_readers;};

26API Reference

1 DCPS API General Description 1.4 Listeners Interfaces

struct DDS_DataReaderListener{

void *listener_data;DDS_DataReaderListener_RequestedDeadlineMissedListener

on_requested_deadline_missed;DDS_DataReaderListener_RequestedIncompatibleQosListener

on_requested_incompatible_qos;DDS_DataReaderListener_SampleRejectedListener

on_sample_rejected;DDS_DataReaderListener_LivelinessChangedListener

on_liveliness_changed;DDS_DataReaderListener_DataAvailableListener

on_data_available;DDS_DataReaderListener_SubscriptionMatchListener

on_subscription_matched;DDS_DataReaderListener_SampleLostListener

on_sample_lost;};/* implemented API operations * <no operations> */

The next paragraphs describes the usage of the DDS_<Entity>Listener structs.

1.4.2 DDS_DomainParticipantListener

Synopsis#include <dds_dcps.h>struct DDS_DomainParticipantListener{ void *listener_data; DDS_DomainParticipantListener_InconsistentTopicListener on_inconsistent_topic; DDS_DomainParticipantListener_OfferedDeadlineMissedListener on_offered_deadline_missed; DDS_DomainParticipantListener_OfferedIncompatibleQosListener on_offered_incompatible_qos; DDS_DomainParticipantListener_LivelinessLostListener on_liveliness_lost; DDS_DomainParticipantListener_PublicationMatchListener on_publication_matched; DDS_DomainParticipantListener_RequestedDeadlineMissedListener on_requested_deadline_missed; DDS_DomainParticipantListener_RequestedIncompatibleQosListener on_requested_incompatible_qos; DDS_DomainParticipantListener_SampleRejectedListener on_sample_rejected; DDS_DomainParticipantListener_LivelinessChangedListener on_liveliness_changed; DDS_DomainParticipantListener_DataAvailableListener on_data_available;

27API Reference

1 DCPS API General Description 1.4 Listeners Interfaces

DDS_DomainParticipantListener_SubscriptionMatchListener on_subscription_matched; DDS_DomainParticipantListener_SampleLostListener on_sample_lost; DDS_DomainParticipantListener_DataOnReadersListener on_data_on_readers;};

DescriptionThe struct DDS_DomainParticipantListener represents the implementation ofthe DomainParticipantListener.

Attributesvoid *listener_data - a pointer to a user-defined object, which may be used

for identification of the Listener.DDS_DomainParticipantListener_InconsistentTopicListener

on_inconsistent_topic - a pointer to the call back functionimplemented by the application.

DDS_DomainParticipantListener_OfferedDeadlineMissedListeneron_offered_deadline_missed - a pointer to the call back function

implemented by the application.DDS_DomainParticipantListener_OfferedIncompatibleQosListener

on_offered_incompatible_qos - a pointer to the call back functionimplemented by the application.

DDS_DomainParticipantListener_LivelinessLostListeneron_liveliness_lost - a pointer to the call back function implemented

by the application.DDS_DomainParticipantListener_PublicationMatchListener

on_publication_matched - a pointer to the call back functionimplemented by the application.

DDS_DomainParticipantListener_RequestedDeadlineMissedListeneron_requested_deadline_missed - a pointer to the call back function

implemented by the application.DDS_DomainParticipantListener_RequestedIncompatible

QosListener on_requested_incompatible_qos -a pointer to the callback function implemented by the application.

DDS_DomainParticipantListener_SampleRejectedListeneron_sample_rejected - a pointer to the call back function implemented

by the application.

28API Reference

1 DCPS API General Description 1.4 Listeners Interfaces

DDS_DomainParticipantListener_LivelinessChangedListeneron_liveliness_changed - a pointer to the call back function

implemented by the application.DDS_DomainParticipantListener_DataAvailableListener

on_data_available - a pointer to the call back function implemented bythe application.

DDS_DomainParticipantListener_SubscriptionMatchListeneron_subscription_matched - a pointer to the call back function

implemented by the application.DDS_DomainParticipantListener_SampleLostListener

on_sample_lost - a pointer to the call back function implemented by theapplication.

DDS_DomainParticipantListener_DataOnReadersListener on_data_on_readers - a pointer to the call back function implemented

by the application.

Detailed DescriptionThe struct DDS_DomainParticipantListener represents the implementation ofthe Listener for the DomainParticipant. Since a Listener is implemented asa struct of pointers, the application must allocate this struct and initialise thesep o i n t e r s . T h e Listener i s a l l o c a t e d u s i n g t h eDDS_DomainParticipantListener__alloc operation. Each pointer mustpoint to the appropriate callback operation defined in the application. It is up to theapplication whether an operation is empty or contains some functionality. Thelistener_data attribute is a pointer to an application-defined object. Thisattribute can be used to supply the identity of the Listener that has been called.Descriptions of the other attributes are given in the appropriate on_<status>callback operations in each Listener.

1.4.3 DDS_ExtDomainParticipantListener

Synopsis#include <dds_dcps.h>struct DDS_ExtDomainParticipantListener{ void *listener_data; DDS_ExtDomainParticipantListener_InconsistentTopicListener

on_inconsistent_topic; DDS_ExtDomainParticipantListener_AllDataDisposed on_all_data_disposed; DDS_ExtDomainParticipantListener_OfferedDeadlineMissedListener

on_offered_deadline_missed; DDS_ExtDomainParticipantListener_OfferedIncompatibleQosListener

29API Reference

1 DCPS API General Description 1.4 Listeners Interfaces

on_offered_incompatible_qos; DDS_ExtDomainParticipantListener_LivelinessLostListener

on_liveliness_lost; DDS_ExtDomainParticipantListener_PublicationMatchListener

on_publication_matched; DDS_ExtDomainParticipantListener_RequestedDeadlineMissedListener

on_requested_deadline_missed; DDS_ExtDomainParticipantListener_RequestedIncompatibleQosListener

on_requested_incompatible_qos; DDS_ExtDomainParticipantListener_SampleRejectedListener

on_sample_rejected; DDS_ExtDomainParticipantListener_LivelinessChangedListener

on_liveliness_changed; DDS_ExtDomainParticipantListener_DataAvailableListener

on_data_available; DDS_ExtDomainParticipantListener_SubscriptionMatchListener

on_subscription_matched; DDS_ExtDomainParticipantListener_SampleLostListener

on_sample_lost; DDS_ExtDomainParticipantListener_DataOnReadersListener

on_data_on_readers;}

DescriptionThe s t ruct DDS_ExtDomainParticipantListener represents theimplementation of the ExtDomainParticipantListener interface, which is anOpenSplice extension to the normal DomainParticipantListener interface thatadds an additional callback operation to handle the ALL_DATA_DISPOSED_STATUSevent.

Attributesvoid *listener_data - a pointer to a user-defined object, which may be used

for identification of the Listener.DDS_ExtDomainParticipantListener_InconsistentTopicListener

on_inconsistent_topic - a pointer to the callback function implementedby the application.

DDS_ExtDomainParticipantListener_AllDataDisposedon_all_data_disposed - a pointer to the callback function implemented bythe application.

DDS_ExtDomainParticipantListener_OfferedDeadlineMissedListener on_offered_deadline_missed - a pointer to the callback functionimplemented by the application.

30API Reference

1 DCPS API General Description 1.4 Listeners Interfaces

DDS_ExtDomainParticipantListener_OfferedIncompatibleQosListener on_offered_incompatible_qos - a pointer to the callback functionimplemented by the application.

DDS_ExtDomainParticipantListener_LivelinessLostListeneron_liveliness_lost - a pointer to the callback function implemented by theapplication.

DDS_ExtDomainParticipantListener_PublicationMatchListeneron_publication_matched - a pointer to the callback function implementedby the application.

DDS_ExtDomainParticipantListener_RequestedDeadlineMissedListener on_requested_deadline_missed - a pointer to the callback functionimplemented by the application.

DDS_ExtDomainParticipantListener_RequestedIncompatibleQosListener on_requested_incompatible_qos - a pointer to thecallback function implemented by the application.

DDS_ExtDomainParticipantListener_SampleRejectedListeneron_sample_rejected - a pointer to the callback function implemented by theapplication.

DDS_ExtDomainParticipantListener_LivelinessChangedListeneron_liveliness_changed - a pointer to the callback function implementedby the application.

DDS_ExtDomainParticipantListener_DataAvailableListeneron_data_available - a pointer to the callback function implemented by theapplication.

DDS_ExtDomainParticipantListener_SubscriptionMatchListeneron_subscription_matched - a pointer to the callback function implementedby the application.

DDS_ExtDomainParticipantListener_SampleLostListeneron_sample_lost - a pointer to the callback function implemented by theapplication.

DDS_ExtDomainParticipantListener_DataOnReadersListeneron_data_on_readers - a pointer to the callback function implemented by theapplication.

31API Reference

1 DCPS API General Description 1.4 Listeners Interfaces

Detailed DescriptionThe struct DDS_ExtDomainParticipantListener represents an extendedimplementation of the Listener for the DomainParticipant. This extension isan OpenSplice addition to the normal DomainParticipantListener interfacea n d a d d s a n a d d i t i o n a l c a l l b a ck o p e r a t i o n t o h a n d l e t h eALL_DATA_DISPOSED_STATUS event.Since a Listener is implemented as a struct of pointers, the application mustallocate this struct and initialise these pointers. This extended Listener isallocated using the DDS_ExtDomainParticipntListener__alloc operation,and may replace the normal DDS_DomainParticipantListener when theALL_DATA_DISPOSED_STATUS needs to be handled. (If this event does not need tobe handled, you can still use the normal DDS_DomainParticipantListenerinstead). Each pointer must point to the appropriate callback operation defined inthe application. It is up to the application whether an operation is empty or containssome functionali ty. The listener_data a t tr ibute is a pointer to anapplication-defined object. This attribute can be used to supply the identity of theListener that has been called.Descriptions of the other attributes are given in the appropriate on_<status>callback operations in each Listener.

1.4.4 DDS_TopicListener

Synopsis#include <dds_dcps.h>struct DDS_TopicListener{ void *listener_data; DDS_TopicListener_InconsistentTopicListener on_inconsistent_topic;};

DescriptionThe struct DDS_TopicListener represents the implementation of theTopicListener.

Attributesvoid *listener_data - a pointer to a user-defined object, which may be used

for identification of the Listener.DDS_TopicListener_InconsistentTopicListener

on_inconsistent_topic - a pointer to the callback functionimplemented by the application.

32API Reference

1 DCPS API General Description 1.4 Listeners Interfaces

Detailed DescriptionThe struct DDS_TopicListener represents the implementation of the Listenerfor the Topic. Since a Listener is implemented as a struct of pointers, theapplication must allocate this struct and initialise these pointers. The Listener isallocated using the DDS_TopicListener__alloc operation. Each pointer mustpoint to the appropriate callback operation defined in the application. It is up to theapplication whether an operation is empty or contains some functionality. Thelistener_data attribute is a pointer to an application-defined object. Thisattribute can be used to supply the identity of the Listener that has been called.Descriptions of the other attributes are given in the appropriate on_<status>callback operations in each Listener.

1.4.5 DDS_ExtTopicListener

Synopsis#include <dds_dcps.h>struct ExtTopicListener{ void *listener_data; DDS_ExtTopicListener_InconsistentTopicListener

on_inconsistent_topic; DDS_ExtTopicListener_AllDataDisposed on_all_data_disposed;}

DescriptionThe struct DDS_ExtTopicListener represents the implementation of theExtTopicListener interface, which is an OpenSplice extension to the normalTopicListener interface that adds an additional callback operation to handle theALL_DATA_DISPOSED_STATUS event.

Attributesvoid *listener_data - a pointer to a user-defined object, which may be used

for identification of the Listener.DDS_ExtTopicListener_InconsistentTopicListener

on_inconsistent_topic - a pointer to the callback function implementedby the application.

DDS_ExtTopicListener_AllDataDisposed on_all_data_disposed - apointer to the callback function implemented by the application.

33API Reference

1 DCPS API General Description 1.4 Listeners Interfaces

Detailed DescriptionThe struct DDS_ExtTopicListener represents an extended implementation of theListener for the Topic. This extension is an OpenSplice addition to the normalTopicListener interface and adds an additional callback operation to handle theALL_DATA_DISPOSED_STATUS event. Since a Listener is implemented as astruct of pointers, the application must allocate this struct and initialise thesep o i n t e r s . T h i s e x t e n d e d Listener i s a l l o c a t e d u s in g t h eDDS_ExtTopicListener__alloc operation, and may replace the normalDDS_TopicListener when the ALL_DATA_DISPOSED_STATUS needs to behandled. (If this event does not need to be handled, you can still use the normalDDS_TopicListener instead). Each pointer must point to the appropriate callbackoperation defined in the application. It is up to the application whether an operationis empty or contains some functionality. The listener_data attribute is a pointerto an application-defined object. This attribute can be used to supply the identity ofthe Listener that has been called.Descriptions of the other attributes are given in the appropriate on_<status>callback operations in each Listener.

1.4.6 DDS_PublisherListener

Synopsis#include <dds_dcps.h>struct DDS_publisherListener{ void *listener_data; DDS_publisherListener_OfferedDeadlineMissedListener on_offered_deadline_missed; DDS_publisherListener_OfferedIncompatibleQosListener on_offered_incompatible_qos; DDS_publisherListener_LivelinessLostListener on_liveliness_lost; DDS_publisherListener_PublicationMatchListener on_publication_matched;};

DescriptionThe struct DDS_publisherListener represents the implementation of thepublisherListener.

Attributesvoid *listener_data - a pointer to a user-defined object, which may be used

for identification of the Listener.

34API Reference

1 DCPS API General Description 1.4 Listeners Interfaces

DDS_publisherListener_OfferedDeadlineMissedListeneron_offered_deadline_missed - a pointer to the call back function

implemented by the application.DDS_publisherListener_OfferedIncompatibleQosListener

on_offered_incompatible_qos - a pointer to the call back functionimplemented by the application.

DDS_publisherListener_LivelinessLostListeneron_liveliness_lost - a pointer to the call back function implemented

by the application.DDS_publisherListener_PublicationMatchListener

on_publication_matched - a pointer to the call back functionimplemented by the application.

Detailed DescriptionThe struct DDS_publisherListener represents the implementation of theListener for the publisher. Since a Listener is implemented as a struct ofpointers, the application must allocate this struct and initialise these pointers. TheListener is allocated using the DDS_publisherListener__alloc operation.Each pointer must point to the appropriate callback operation defined in theapplication. It is up to the application whether an operation is empty or containssome functionali ty. The listener_data a t tr ibute is a pointer to anapplication-defined object. This attribute can be used to supply the identity of theListener that has been called. Descriptions of the other attributes are given in theappropriate on_<status> callback operations in each Listener.

1.4.7 DDS_DataWriterListener

Synopsis#include <dds_dcps.h>struct DDS_DataWriterListener{ DDS_DataWriterListener_OfferedDeadlineMissedListener on_offered_deadline_missed; DDS_DataWriterListener_OfferedIncompatibleQosListener on_offered_incompatible_qos; DDS_DataWriterListener_LivelinessLostListener on_liveliness_lost; DDS_DataWriterListener_PublicationMatchListener on_publication_matched;};

35API Reference

1 DCPS API General Description 1.4 Listeners Interfaces

DescriptionThe struct DDS_DataWriterListener represents the implementation of theDataWriterListener.

Attributesvoid *listener_data - a pointer to a user-defined object, which may be used

for identification of the Listener.DDS_DataWriterListener_OfferedDeadlineMissedListener

on_offered_deadline_missed - a pointer to the call back functionimplemented by the application.

DDS_DataWriterListener_OfferedIncompatibleQosListeneron_offered_incompatible_qos - a pointer to the call back function

implemented by the application.DDS_DataWriterListener_LivelinessLostListener

on_liveliness_lost - a pointer to the call back function implementedby the application.

DDS_DataWriterListener_PublicationMatchListeneron_publication_matched - a pointer to the call back function

implemented by the application.

Detailed DescriptionThe struct DDS_DataWriterListener represents the implementation of theListener for the DataWriter. Since a Listener is implemented as a struct ofpointers, the application must allocate this struct and initialise these pointers. TheListener is allocated using the DDS_DataWriterListener__alloc operation.Each pointer must point to the appropriate callback operation defined in theapplication. It is up to the application whether an operation is empty or containssome functionali ty. The listener_data a t tr ibute is a pointer to anapplication-defined object. This attribute can be used to supply the identity of theListener that has been called. Descriptions of the other attributes are given in theappropriate on_<status> callback operations in each Listener.

1.4.8 DDS_SubscriberListener

Synopsis#include <dds_dcps.h>struct DDS_SubscriberListener{ void *listener_data; DDS_SubscriberListener_RequestedDeadlineMissedListener on_requested_deadline_missed;

36API Reference

1 DCPS API General Description 1.4 Listeners Interfaces

DDS_SubscriberListener_RequestedIncompatibleQosListener on_requested_incompatible_qos; DDS_SubscriberListener_SampleRejectedListener on_sample_rejected; DDS_SubscriberListener_LivelinessChangedListener on_liveliness_changed; DDS_SubscriberListener_DataAvailableListener on_data_available; DDS_SubscriberListener_SubscriptionMatchListener on_subscription_matched; DDS_SubscriberListener_SampleLostListener on_sample_lost; DDS_SubscriberListener_DataOnReadersListener on_data_on_readers;};

DescriptionThe struct DDS_SubscriberListener represents the implementation of theSubscriberListener.

Attributesvoid *listener_data - a pointer to a user-defined object, which may be used

for identification of the Listener.DDS_SubscriberListener_RequestedDeadlineMissedListener

on_requested_deadline_missed - a pointer to the call back functionimplemented by the application.

DDS_SubscriberListener_RequestedIncompatibleQosListeneron_requested_incompatible_qos - a pointer to the call back function

implemented by the application.DDS_SubscriberListener_SampleRejectedListener

on_sample_rejected - a pointer to the call back function implementedby the application.

DDS_SubscriberListener_LivelinessChangedListeneron_liveliness_changed - a pointer to the call back function

implemented by the application.DDS_SubscriberListener_DataAvailableListener

on_data_available - a pointer to the call back function implemented bythe application.

DDS_SubscriberListener_SubscriptionMatchListeneron_subscription_matched - a pointer to the call back function

implemented by the application.

37API Reference

1 DCPS API General Description 1.4 Listeners Interfaces

DDS_SubscriberListener_SampleLostListener on_sample_lost - apointer to the call back function implemented by the application.

DDS_SubscriberListener_DataOnReadersListeneron_data_on_readers - a pointer to the call back function implemented

by the application.

Detailed DescriptionThe struct DDS_SubscriberListener represents the implementation of theListener for the Subscriber. Since a Listener is implemented as a struct ofpointers, the application must allocate this struct and initialise these pointers. TheListener is allocated using the DDS_SubscriberListener__alloc operation.Each pointer must point to the appropriate callback operation defined in theapplication. It is up to the application whether an operation is empty or containssome functionali ty. The listener_data a t tr ibute is a pointer to anapplication-defined object. This attribute can be used to supply the identity of theListener that has been called. Descriptions of the other attributes are given in theappropriate on_<status> callback operations in each Listener.

1.4.9 DDS_DataReaderListener

Synopsis#include <dds_dcps.h>struct DDS_DataReaderListener{ void *listener_data; DDS_DataReaderListener_RequestedDeadlineMissedListener on_requested_deadline_missed; DDS_DataReaderListener_RequestedIncompatibleQosListener on_requested_incompatible_qos; DDS_DataReaderListener_SampleRejectedListener on_sample_rejected; DDS_DataReaderListener_LivelinessChangedListener on_liveliness_changed; DDS_DataReaderListener_DataAvailableListener on_data_available; DDS_DataReaderListener_SubscriptionMatchListener on_subscription_matched; DDS_DataReaderListener_SampleLostListener

on_sample_lost;};

38API Reference

1 DCPS API General Description 1.4 Listeners Interfaces

DescriptionThe struct DDS_DataReaderListener represents the implementation of theDataReaderListener.

Attributesvoid *listener_data - a pointer to a user-defined object, which may be used

for identification of the Listener.DDS_DataReaderListener_RequestedDeadlineMissedListener

on_requested_deadline_missed - a pointer to the call back functionimplemented by the application.

DDS_DataReaderListener_RequestedIncompatibleQosListeneron_requested_incompatible_qos - a pointer to the call back function

implemented by the application.DDS_DataReaderListener_SampleRejectedListener

on_sample_rejected - a pointer to the call back function implementedby the application.

DDS_DataReaderListener_LivelinessChangedListeneron_liveliness_changed - a pointer to the call back function

implemented by the application.DDS_DataReaderListener_DataAvailableListener

on_data_available - a pointer to the call back function implemented by theapplication.

DDS_DataReaderListener_SubscriptionMatchListeneron_subscription_matched - a pointer to the call back functionimplemented by the application.

DDS_DataReaderListener_SampleLostListener on_sample_lost - apointer to the call back function implemented by the application.

Detailed DescriptionThe struct DDS_DataReaderListener represents the implementation of theListener for the DataReader. Since a Listener is implemented as a struct ofpointers, the application must allocate this struct and initialise these pointers. TheListener is allocated using the DDS_DataReaderListener__alloc operation.Each pointer must point to the appropriate callback operation defined in theapplication. It is up to the application whether an operation is empty or containssome functionali ty. The listener_data a t tr ibute is a pointer to anapplication-defined object. This attribute can be used to supply the identity of theListener that has been called. Descriptions of the other attributes are given in theappropriate on_<status> callback operations in each Listener.

39API Reference

1 DCPS API General Description 1.5 Inheritance of Abstract Operations

1.5 Inheritance of Abstract OperationsThe information provided here conforms to the• PIM part of the DDS-DCPS specification (for module descriptions)• PSM part of the DDS-DCPS specification (for class and operation descriptions).For detailed information refer to the OMG C Language Mapping Specification.At PIM level, inheritance is used to define abstract classes and operations. TheOMG IDL PSM defines the interface for an application to interact with the DataDistribution Service. The DCPS API for the C programming language conforms tothe IDL to C mapping as specified in the OMG C Language Mapping Specification.Inheritance of operations is not implemented when different type parameters for thesame operation are used. In this case operations are implemented in their respectivederived class (e.g. DDS_<Entity>_get_qos and DDS_<Entity>_set_qos).These operations are commented out in the IDL PSM.

40API Reference

CHAPTER

2 DCPS ModulesDCPS is divided into five modules, which are described briefly in this chapter. Eachmodule consists of several classes as defined at PIM level in the DDS-DCPSspecification. Some of the classes as described in the PIM are implemented as astruct in the PSM; these classes are treated as a class in this chapter according tothe PIM with a remark about their implementation (struct). In the next chapter theiractual implementations are described.Each class contains several operations, which may be abstract. Those classes,which are implemented as a struct do not have any operations. The modules and theclasses are ordered conform the DDS-DCPS specification. The classes, interfaces,structs and operations are described in the next chapter.

Figure 2: DCPS Module Composition

2.1 FunctionalityThe modules have the following function in the Data Distribution Service:• Infrastructure Module: This module defines the abstract classes and interfaces,

which are refined by the other modules. It also provides the support for theinteraction between the application and the Data Distribution Service (state-basedand event-based)

Domain Module

PublicationModule

SubscriptionModule

Topic-DefinitionModule

InfrastructureModule

41 API Reference

2 DCPS Modules 2.2 Infrastructure Module

• Domain Module - This module contains the DDS_DomainParticipant class,which is the entry point of the application, theDDS_DomainParticipantFactory class andDDS_DomainParticipantListener interface

• Topic-Definition Module - This module contains the DDS_Topic,DDS_ContentFilteredTopic and DDS_MultiTopic classes. It also containsthe DDS_TopicListener interface and all support to define DDS_Topic objectsand assign QosPolicy settings to them

• Publication Module - This module contains the DDS_Publisher andDDS_DataWriter classes. It also contains the DDS_PublisherListener andDDS_DataWriterListener interfaces

• Subscription Module - This module contains the DDS_Subscriber,DDS_DataReader, DDS_ReadCondition and DDS_QueryConditionclasses. It also contains the DDS_SubscriberListener andDDS_DataReaderListener interfaces

2.2 Infrastructure ModuleThis module defines the abstract classes and interfaces, which, in the PIMdefinition, are refined by the other modules. It also provides the support for theinteraction between the application and the Data Distribution Service (event-basedand state-based). The event-based interaction is supported by DDS_Listeners, thestate-based interaction is supported by DDS_WaitSets and DDS_Conditions.

Figure 3: DCPS Infrastructure Module’s Class Model

GuardCondition

set_trigger_value()

Condition

get_trigger_value()

WaitSet

attach_condition()detach_condition()get_conditions()wait()

*

*

*

*

QosPolicy

name : string

Status

StatusCondition

get_enabled_statuses()get_entity()set_enabled_statuses()

Listener

<<Interface>>Entity

enable()<<abstract>> get_listener()<<abstract>> get_qos()get_status_changes()get_statuscondition()<<abstract>> set_listener()<<abstract>> set_qos()

**

qos

* 1* 1

status

11

entity

0..10..1

statuscondition

0..1* 0..1*

listener

DomainParticipant(from Domain Module) DomainEntity**11

ReadCondition(from Subscription Module)

QueryCondition(from Subscription Module)

42API Reference

2 DCPS Modules 2.3 Domain Module

This module contains the following classes:• DDS_Entity (abstract)• DDS_DomainEntity (abstract)• DDS_QosPolicy (abstract, struct)• DDS_Listener (interface)• DDS_Status (abstract, struct)• DDS_WaitSet

• DDS_Condition

• DDS_GuardCondition

• DDS_StatusCondition

2.3 Domain ModuleThis module contains the class DDS_DomainParticipant, which acts as an entrypoint of the Data Distribution Service and acts as a factory for many of the classes.The DDS_DomainParticipant also acts as a container for the other objects thatmake up the Data Distribution Service. It isolates applications within the sameDomain from other applications in a different Domain on the same set ofcomputers. A Domain is a “virtual network” and applications with the samedomainId are isolated from applications with a different domainId. In this way,several independent distributed applications can coexist in the same physicalnetwork without interfering, or even being aware of each other.

43API Reference

2 DCPS Modules 2.4 Topic-Definition Module

Figure 4: DCPS Domain Module’s Class ModelThis module contains the following classes:• DDS_DomainParticipant

• DDS_DomainParticipantFactory

• DDS_DomainParticipantListener (interface)• DDS_Domain (not depicted)

2.4 Topic-Definition ModuleThis module contains the DDS_Topic, DDS_ContentFilteredTopic andDDS_MultiTopic classes. It also contains the DDS_TopicListener interface andall support to define DDS_Topic objects and assign QosPolicy settings to them.

SubscriberListener(from Subscription Module)

<<Interface>>

TopicListener

on_inconsistent_topic()

<<Interface>>

PublisherListener(from Publication Module)

<<Interface>> Entity(from Infrastructure Module)

Publisher(from Publication Module)

Subscriber(from Subscription Module)

ContentFilteredTopic(from Topic-Definition Module)

MultiTopic(from Topic-Definition Module)DomainParticipantFactory

create_participant()

delete_participant()get_default_participant_qos()get_instance()lookup_participant()set_default_participant_qos()

DomainEntity(from Infrastructure Module)

QosPolicy(from Infrastructure Module)

**

default_participant_qos

DomainParticipantListener

DomainParticipant

assert_liveliness()contains_entity()create_contentfilteredtopic()create_multitopic()create_publisher()create_subscriber()create_topic()delete_contained_entities()delete_contentfilteredtopic()delete_multitopic()delete_publisher()delete_subscriber()delete_topic()find_topic()get_builtin_subscriber()get_current_time()get_default_publisher_qos()get_default_subscriber_qos()get_default_topic_qos()get_domain_id()get_listener()get_qos()ignore_participant()ignore_publication()ignore_subscription()ignore_topic()lookup_topic_description()set_default_publisher_qos()set_default_subscriber_qos()set_default_topic_qos()set_listener()set_qos()

**

11

**

qos<<implicit>>

**default_publisher_qos

** default_topic_qos**

default_subscriber_qos

0..10..1

<<implicit>>

Topic(from Topic-Definition Module)

TopicDescription(from Topic-Definition Module)

**

<<implicit>>

<<create>>

<<create>>

<<create>>

<<create>>

<<create>>

<<create>>

delete_contained_entities()

44API Reference

2 DCPS Modules 2.4 Topic-Definition Module

Figure 5: DCPS Topic-Definition Module’s Class Model This module contains the following classes:• DDS_TopicDescription (abstract)• DDS_Topic

• DDS_ContentFilteredTopic

• DDS_MultiTopic

• DDS_TopicListener (interface)• Topic-Definition type specific classesTopic-Definition type specific classes contain the generic class and the generateddata type specific classes. In case of the user-defined data type Foo (this also appliesto other types), defined in the module SPACE; “Topic-Definition type specificclasses” contains the following classes:• DDS_TypeSupport (abstract)• SPACE_FooTypeSupport

DomainEntity(from Infrastructure Module)

DataReader(from Subscription Module)

TypeSupport

get_type_name()register_type()

<<Interface>>

TopicDescription

get_name()get_participant()get_type_name()

1

*

1

*

11

DomainParticipant(from Domain Module)

TopicListener

on_inconsistent_topic()

<<Interface>>QosPolicy(from Infrastructure Module)

DataWriter(from Publication Module)

MultiTopic

get_expression_parameters()get_subscription_expression()set_expression_parameters()

ContentFilteredTopic

get_expression_parameters()get_filter_expression()get_related_topic()set_expression_parameters()

Topic

get_inconsistent_topic_status()get_listener()get_qos()set_listener()set_qos()

0..10..1**

1* 1*

**

11

WaitSet(from Infrastructure Module)

StatusCondition(from Infrastructure Module)

*

1

*

1

** **

<<create>>

<<create>>

<<create>>

45API Reference

2 DCPS Modules 2.5 Publication Module

Figure 6: Data Type “Foo” Typed Classes Pre-processor Generation

2.5 Publication ModuleThis module supports writing of the data, it contains the DDS_Publisher andDDS_DataWriter classes. It also contains the DDS_PublisherListener andDDS_DataWriterListener interfaces. Furthermore, it contains all supportneeded for publication.

TypeSupport

get_type_name()register_type()

<<Interface>> DataWriter(from Publication Module)

DataReader(from Subscription Module)

FooDataReader

get_key_value()read()read_instance()read_next_instance()read_next_instance_w_condition()read_next_sample()read_w_condition()return_loan()take()take_instance()take_next_instance()take_next_instance_w_condition()take_next_sample()take_w_condition()

FooDataWriter

dispose()dispose_w_timestamp()get_key_value()register()register_w_timestamp()unregister()unregister_w_timestamp()write()write_w_timestamp()

Foo

FooTypeSupport

get_type_name()register_type()

46API Reference

2 DCPS Modules 2.5 Publication Module

Figure 7: DCPS Publication Module’s Class Model

This module contains the following classes:• DDS_Publisher

• DDS_PublisherListener (interface)• DDS_DataWriterListener (interface)• Publication type specific classesPublication type specific classes contain the generic class and the generated datatype specific classes. In case of the user-defined data type Foo (this also applies toother types), defined in the module SPACE; “Publication type specific classes”contains the following classes:• DDS_DataWriter (abstract)• SPACE_FooDataWriter

WaitSet(from Infrastructure Module)

PublisherListener

<<Interface>>

DomainParticipant(from Domain Module)

DataWriterListener

on_liveliness_lost()on_offered_deadline_missed()on_offered_incompatible_qos()on_publication_match()

<<Interface>>

StatusCondition(from Infrastructure Module)

*

*

*

*

Publisher

begin_coherent_changes()copy_from_topic_qos()create_datawriter()delete_contained_entities()delete_datawriter()end_coherent_changes()get_default_datawriter_qos()get_listener()get_participant()get_qos()lookup_datawriter()resume_publications()set_default_datawriter_qos()set_listener()set_qos()suspend_publications()

1

*

1

*

<<implicit>>

1

0..1

1

0..1 <<implicit>>

QosPolicy(from Infrastructure Module)

**qos

<<implicit>>

**

default_datawriter_qos

DataWriter

assert_liveliness()<<abstract>> dispose()<<abstract>> dispose_w_timestamp()<<abstract>> get_key_value()get_listener()get_liveliness_lost_status()get_matched_subscription_data()get_matched_subscriptions()get_offered_deadline_missed_status()get_offered_incompatible_qos_status()get_publication_match_status()get_publisher()get_qos()get_topic()<<abstract>> register()<<abstract>> register_w_timestamp()set_listener()set_qos()<<abstract>> unregister()<<abstract>> unregister_w_timestamp()<<abstract>> write()<<abstract>> write_w_timestamp()

0..1

*

0..1

*

<<implicit>>

1

0..1

1

0..1

<<implicit>>

**

<<implicit>>

1

*

1

*

Topic(from Topic-Definition Module)

**

* 1* 1

<<create>>

<<create>>

47API Reference

2 DCPS Modules 2.6 Subscription Module

2.6 Subscription ModuleThis module supports access to the data, it contains the DDS_Subscriber,DDS_DataReader, DDS_ReadCondition and DDS_QueryCondition classes.I t a l so con t a in s t he DDS_SubscriberListener a n dDDS_DataReaderListener interfaces. Furthermore, it contains all supportneeded for subscription.

Figure 8: DCPS Subscription Module’s Class ModelThis module contains the following classes:• DDS_Subscriber

• DDS_DataSample

• DDS_SampleInfo (struct)

QueryCondition

get_query_parameters()get_query_expression()set_query_parameters()

DomainParticipant(from Domain Module)

SampleInfosample_stateview_stateinstance_statesource_timestampinstance_handledisposed_generation_countno_writers_generation_countsample_rankgeneration_rankabsolute_generation_rank

WaitSet(from Infrastructure Module)

Topic(from Topic-Definition Module)

SubscriberListener

on_data_on_readers()

<<Interface>>

TopicDescription(from Topic-Definition Module)

**

<<implicit>>

DataReaderListener

on_data_available()on_liveliness_changed()on_requested_deadline_missed()on_requested_incompatible_qos()on_sample_lost()on_sample_rejected()on_subscription_match()

<<Interface>>

DataSample

11

ReadCondition

get_datareader()get_instance_state_mask()get_sample_state_mask()get_view_state_mask()

*

*

*

*<<implicit>>

StatusCondition(from Infrastructure Module)

** **

QosPolicyname : string

**

Subscriber

begin_access()copy_from_topic_qos()create_datareader()delete_contained_entities()delete_datareader()end_access()get_datareaders()get_default_datareader_qos()get_listener()get_participant()get_qos()lookup_datareader()notify_datareaders()set_default_datareader_qos()set_listener()set_qos()

0..10..1

<<implicit>>

1

0..1

1

0..1

<<implicit>>

**

qos<<implicit>>

**

default_datareader_qos

DataReader

create_querycondition()create_readcondition()delete_contained_entities()delete_readcondition()<<abstract>> get_key_value()get_listener()get_liveliness_changed_status()get_matched_publication_data()get_matched_publications()get_qos()get_requested_deadline_missed_status()get_requested_incompatible_qos_status()get_sample_lost_status()get_sample_rejected_status()get_subscriber()get_subscription_match_status()get_topicdescription()<<abstract>> lookup_instance()<<abstract>> read()<<abstract>> read_instance()<<abstract>> read_next_instance()<<abstract>> read_next_instance_w_condition()<<abstract>> read_next_sample()<<abstract>> read_w_condition()<<abstract>> return_loan()set_listener()set_qos()<<abstract>> take()<<abstract>> take_instance()<<abstract>> take_next_instance()<<abstract>> take_next_instance_w_condition()<<abstract>> take_next_sample()<<abstract>> take_w_condition()

*1

*1

0..10..1

**

*

1

*

1

0..1

<<implicit>>

**

<<implicit>>

1

*

1

*

<<create>>

<<create>>

<<create>>

<<create>>

48API Reference

2 DCPS Modules 2.6 Subscription Module

• DDS_SubscriberListener (interface)• DDS_DataReaderListener (interface)• DDS_ReadCondition

• DDS_QueryCondition

• Subscription type specific classesSubscription type specific classes contain the generic class and the generated datatype specific classes. In case of the user-defined data type Foo (this also applies toother types), defined in the module SPACE; “Subscription type specific classes”contains the following classes:• DDS_DataReader (abstract)• SPACE_FooDataReader

49API Reference

2 DCPS Modules 2.6 Subscription Module

50API Reference

CHAPTER

3 DCPS Classes and OperationsThis chapter describes, for each module, its classes and operations in detail. Eachmodule consists of several classes as defined at PIM level in the DDS-DCPSspecification. Some of the classes are implemented as a struct in the PSM. Some ofthe other classes are abstract, which means they contain some abstract operations.The Listener interfaces are designed as an interface at PIM level. In other words,the application must implement the interface operations. Therefore, all Listenerclasses are abstract. A user-defined class for these operations must be provided bythe application which must extend from the specific Listener class. All Listeneroperations must be implemented in the user-defined class. It is up to the applicationwhether an operation is empty or contains some functionality. The Listener interfaces in the C API are implemented as structs containingfunction pointers. All the function pointer attributes within the struct must beassigned to a function. It is up to the application whether a function is empty orcontains some functionality.Each class contains several operations, which may be abstract (base class).Abstract operations are not implemented in their base class, but in a type specificclass or an application-defined class (in case of a Listener). Classes that areimplemented as a struct do not have any operations. Some operations are inherited,which means they are implemented in their base class.The abstract operations in a class are listed (including their synopsis), but notimplemented in that class. These operations are implemented in their respectivederived classes. The interfaces are fully described, since they must be implementedby the application.

General note for type Space: The name Space.h is derived from the IDL fileSpace.idl, that defines Foo.

i

51 API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

3.1 Infrastructure Module

Figure 9: DCPS Infrastructure Module’s Class Model

This module contains the following classes:• DDS_Entity (abstract)• DDS_DomainEntity (abstract)• DDS_QosPolicy (abstract, struct)• DDS_Listener (interface)• DDS_Status (abstract, struct)• DDS_WaitSet• DDS_Condition• DDS_GuardCondition• DDS_StatusCondition

• DDS_ErrorInfo

3.1.1 Class DDS_Entity (abstract)This class is the abstract base class for all the DCPS objects. It acts as a generic classfor DDS_Entity objects.The interface description of this class is as follows:

/* interface DDS_Entity *//* abstract operations (implemented in class

DDS_DomainParticipant, * DDS_Topic, DDS_Publisher, DDS_DataWriter, DDS_Subscriber and

GuardCondition

set_trigger_value()

Condition

get_trigger_value()

WaitSet

attach_condition()detach_condition()get_conditions()wait()

*

*

*

*

QosPolicy

name : string

Status

StatusCondition

get_enabled_statuses()get_entity()set_enabled_statuses()

Listener

<<Interface>>Entity

enable()<<abstract>> get_listener()<<abstract>> get_qos()get_status_changes()get_statuscondition()<<abstract>> set_listener()<<abstract>> set_qos()

**

qos

* 1* 1

status

11

entity

0..10..1

statuscondition

0..1* 0..1*

listener

DomainParticipant(from Domain Module) DomainEntity**11

ReadCondition(from Subscription Module)

QueryCondition(from Subscription Module)

52API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

* DDS_DataReader) *//* * DDS_ReturnCode_t * DDS_Entity_set_qos * (DDS_Entity _this, * const DDS_EntityQos *qos); *//* * DDS_ReturnCode_t * DDS_Entity_get_qos * (DDS_Entity _this, * DDS_EntityQos *qos); *//* * DDS_ReturnCode_t * DDS_Entity_set_listener * (DDS_Entity _this, * const struct DDS_EntityListener *a_listener, * const DDS_StatusMask mask); *//* * struct DDS_EntityListener * DDS_Entity_get_listener * (DDS_Entity _this); *//* * implemented API operations */

DDS_ReturnCode_t DDS_Entity_enable (DDS_Entity _this);DDS_StatusCondition DDS_Entity_get_statuscondition (DDS_Entity _this);DDS_StatusMask DDS_Entity_get_status_changes (DDS_Entity _this);DDS_InstanceHandle_t DDS_Entity_get_instance_handle (DDS_Entity _this);

The abstract operations are listed but not fully described because they are notimplemented in this specific class. The full description of these operations is givenin the subclasses, which contain the type specific implementation of theseoperations.

53API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

3.1.1.1 DDS_Entity_enable

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Entity_enable (DDS_Entity _this);

DescriptionThis operation enables the DDS_Entity on which it is being called when theDDS_Entity was created with the DDS_EntityFactoryQosPolicy set toFALSE.

Parametersin DDS_Entity _this - the DDS_Entity object on which the operation is

operated.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_ALREADY_DELETED , DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionThis operation enables the DDS_Entity. Created DDS_Entity objects can start ineither an enabled or disabled state. This is controlled by the value of theDDS_EntityFactoryQosPolicy on the corresponding factory for theDDS_Entity. Enabled entities are immediately activated at creation time meaningall their immutable QoS settings can no longer be changed. Disabled Entities are notyet activated, so it is still possible to change their immutable QoS settings. However,once activated the immutable QoS settings can no longer be changed.Creating disabled entities can make sense when the creator of the DDS_Entitydoes not yet know which QoS settings to apply, thus allowing another piece of codeto set the QoS later on. The default setting of DDS_EntityFactoryQosPolicy is such that, by default,entities are created in an enabled state so that it is not necessary to explicitly callDDS_<Entity>_enable on newly-created entities.The DDS_<Entity>_enable operation produces the same results no matter howmany times it is performed. Calling DDS_<Entity>_enable on an alreadyenabled DDS_Entity returns DDS_RETCODE_OK and has no effect.

54API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

If a DDS_Entity has not yet been enabled, the only operations that can be invokedon it are: the ones to set, get or copy the QosPolicy settings (including the defaultQosPolicy settings on factories), the ones that set (or get) the listener, the ones thatget the DDS_StatusCondition, the DDS_Entity_get_status_changesoperation (although the status of a disabled entity never changes), and the ‘factory’operations that create, delete or lookup1 other DDS_Entities. Other operationswill return the error DDS_RETCODE_NOT_ENABLED.Entities created from a factory that is disabled, are created disabled regardless ofthe setting of the DDS_EntityFactoryQosPolicy.Calling DDS_<Entity>_enable on an DDS_Entity whose factory is not enabledwill fail and return DDS_RETCODE_PRECONDITION_NOT_MET.If the DDS_EntityFactoryQosPolicy has autoenable_created_entitiesset to TRUE, the DDS_<Entity>_enable operation on the factory willautomatically enable all Entities created from the factory.The Listeners associated with an DDS_Entity are not called until theDDS_Entity is enabled. DDS_Conditions associated with an DDS_Entity thatis not enabled are "inactive", that is, have a trigger_value which is FALSE.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the application enabled the DDS_Entity (or it was already

enabled)• DDS_RETCODE_ERROR - an internal error has occurred• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation• DDS_RETCODE_PRECONDITION_NOT_MET - the factory of the DDS_Entity is

not enabled

3.1.1.2 DDS_Entity_get_instance_handle

Synopsis#include <dds_dcps.h>DDS_InstanceHandle_t DDS_Entity_get_instance_handle (DDS_Entity _this);

1. This includes the lookup_topicdescription, but not the find_topic.

55

API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

DescriptionThis operation returns the instance_handle of the built-in topic sample thatrepresents the specified DDS_Entity.

Parametersin DDS_Entity _this - object on which the operation is operated.

Return ValueDDS_InstanceHandle_t - Result value is the instance_handle of the built-in

topic sample that represents the state of this DDS_Entity.

Detailed DescriptionThe relevant state of some DDS_Entity objects are distributed using built-in topics.Each built-in topic sample represents the state of a specific DDS_Entity and has aunique instance_handle. This operation returns the instance_handle of thebuilt-in topic sample that represents the specified DDS_Entity. Some DDS_Entities (DDS_Publisher and DDS_Subscriber) do not have acorresponding built-in topic sample, but they still have an instance_handle thatuniquely identifies the DDS_Entity.The instance_handles obtained this way can also be used to check whether aspecific DDS_Entity is located in a specific DDS_DomainParticipant. (SeeSection 3.2.1.2, DDS_DomainParticipant_contains_entity, on page 167.)

3.1.1.3 DDS_Entity_get_listener (abstract)This abstract operation is defined as a generic operation to access a Listener.Each subclass derived from this class, DDS_DomainParticipant, DDS_Topic,DDS_Publisher, DDS_Subscriber, DDS_DataWriter and DDS_DataReaderwill provide a class specific implementation of this abstract operation.

Synopsis#include <dds_dcps.h>struct DDS_EntityListener DDS_Entity_get_listener (DDS_Entity _this);

3.1.1.4 DDS_Entity_get_qos (abstract)This abstract operation is defined as a generic operation to access a struct with theQosPolicy s e t t i n g s . E a c h s u b c l a s s d e r i v e d f r o m t h i s c l a s s ,DDS_DomainParticipant, DDS_Topic, DDS_Publisher, DDS_Subscriber,DDS_DataWriter and DDS_DataReader will provide a class specificimplementation of this abstract operation.

56API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Entity_get_qos (DDS_Entity _this, DDS_EntityQos *qos);

3.1.1.5 DDS_Entity_get_status_changes

Synopsis#include <dds_dcps.h>DDS_StatusMask DDS_Entity_get_status_changes (DDS_Entity _this);

DescriptionThis operation returns a mask with the communication statuses in the DDS_Entitythat are “triggered”.

Parametersin DDS_Entity _this - object on which the operation is operated.

Return ValueDDS_StatusMask - Result is a bit-mask in which each bit shows which value has

changed.

Detailed DescriptionThis operation returns a mask with the communication statuses in the DDS_Entitythat are “triggered”. That is the set of communication statuses whose value havechanged since the last time the application called this operation. This operationshows whether a change has occurred even when the status seems unchangedbecause the status changed back to the original status.When the DDS_Entity is first created or if the DDS_Entity is not enabled, allcommunication statuses are in the “un-triggered” state so the mask returned by theoperation is empty.The result value is a bit-mask in which each bit shows which value has changed.The relevant bits represent one of the following statuses:• DDS_INCONSISTENT_TOPIC_STATUS

• DDS_OFFERED_DEADLINE_MISSED_STATUS

• DDS_REQUESTED_DEADLINE_MISSED_STATUS

• DDS_OFFERED_INCOMPATIBLE_QOS_STATUS

57API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

• 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

Each status bit is declared as a constant and can be used in an AND operation tocheck the status bit against the result of type DDS_StatusMask. Not all statuses arerelevant to all DDS_Entity objects. See the respective Listener interfaces foreach DDS_Entity for more information.

3.1.1.6 DDS_Entity_get_statuscondition

Synopsis#include <dds_dcps.h>DDS_StatusCondition DDS_Entity_get_statuscondition (DDS_Entity _this);

DescriptionThis operation allows access to the DDS_StatusCondition associated with theDDS_Entity.

Parametersin DDS_Entity _this - object on which the operation is operated.

Return ValueDDS_StatusCondition - Result value is the DDS_StatusCondition of the

DDS_Entity.

Detailed DescriptionEach DDS_Entity has a DDS_StatusCondition associated with it. Thisoperation allows access to the DDS_StatusCondition associated with theDDS_Entity. The returned condition can then be added to a DDS_WaitSet so thatthe application can wait for specific status changes that affect the DDS_Entity.

58API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

3.1.1.7 DDS_Entity_set_listener (abstract)This abstract operation is defined as a generic operation to access a Listener.Each subclass derived from this class, DDS_DomainParticipant, DDS_Topic,DDS_Publisher, DDS_Subscriber, DDS_DataWriter and DDS_DataReaderwill provide a class specific implementation of this abstract operation.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Entity_set_listener (DDS_Entity _this, const struct DDS_Listener *a_listener, const DDS_StatusMask mask);

3.1.1.8 DDS_Entity_set_qos (abstract)This abstract operation is defined as a generic operation to modify a struct with theQosPolicy s e t t i n g s . E a c h s u b c l a s s d e r i v e d f r o m t h i s c l a s s ,DDS_DomainParticipant, DDS_Topic, DDS_Publisher, DDS_Subscriber,DDS_DataWriter and DDS_DataReader will provide a class specificimplementation of this abstract operation.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Entity_set_qos (DDS_Entity _this, const DDS_EntityQos *qos);

3.1.2 Class DDS_DomainEntity (abstract)T h i s c l a s s i s t h e a b s t r a c t b a s e c l a s s f o r t h e a l l e n t i t i e s e x c e p tDDS_DomainParticipant . T h e m a i n p u r p o s e i s t o e x p r e s s t h a tDDS_DomainParticipant is a special kind of DDS_Entity, which acts as acontainer of all other DDS_Entity objects, but cannot contain anotherDDS_DomainParticipant within itself. Therefore, this class is not part of the IDLinterface in the DCPS PSM description.The class DDS_DomainEntity does not contain any operations.

3.1.3 Struct QosPolicyEach DDS_Entity provides a <DDS_Entity>Qos structure that implements thebasic mechanism for an application to specify Quality of Service attributes. Thisstructure consists of DDS_Entity specific QosPolicy attributes. QosPolicy

59API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

attributes are structured types where each type specifies the information thatcontrols an DDS_Entity related (configurable) property of the Data DistributionService.All QosPolicies applicable to a DDS_Entity are aggregated in a corresponding<DDS_Entity>Qos, which is a compound structure that is set atomically so that itrepresents a coherent set of QosPolicy attributes.Compound types are used whenever multiple attributes must be set coherently todefine a consistent attribute for a QosPolicy.See Appendix A, Quality Of Service for details of the <DDS_Entity>Qos, alongwith a complete list of individual QosPolicy settings and their meanings.

60API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

Figure 10: QosPolicy Settings

Requested/OfferedIn several cases, for communications to occur properly (or efficiently), aQosPolicy on the requesting side must be compatible with a correspondingQosPolicy on the offering side. For example, if a DDS_DataReader requests toreceive data reliably while the corresponding DDS_DataWriter defines abest-effort QosPolicy, communication will not happen as requested. This means

autodispose_unregistered_instances : boolean

WriterDataLifecycleQosPolicy

value : long

OwnershipStrengthQosPolicy

kind : OwnershipQosPolicyKind

OwnershipQosPolicy

duration : Duration_t

LifespanQosPolicy

kind : HistoryQosPolicyKinddepth : long

HistoryQosPolicy

minimum_separation : Duration_t

TimeBasedFilterQosPolicy

autoenable_created_entities : boolean

EntityFactoryQosPolicy

duration : Duration_t

DeadlineQosPolicy

duration : Duration_t

LatencyBudgetQosPolicy

value [*] : octet

GroupDataQosPolicy

value [*] : octet

TopicDataQosPolicy

value [*] : octet

UserDataQosPolicy

kind : DestinationOrderQosPolicyKind

DestinationOrderQosPolicy

value : long

TransportPriorityQosPolicy

max_samples : longmax_instances : longmax_samples_per_instance : long

ResourceLimitsQosPolicy

kind : DurabilityQosPolicyKind

DurabilityQosPolicy

kind : LivelinessQosPolicyKindlease_duration : Duration_t

LivelinessQosPolicy

kind : ReliabilityQosPolicyKindmax_blocking_time : Duration_tsynchronous : boolean

ReliabilityQosPolicy

name[*] : string

PartitionQosPolicy

service_cleanup_delay : Duration_thistory_kind : HistoryQosPolicyKindhistory_depth : longmax_samples : longmax_instances : longmax_samples_per_instance : long

DurabilityServiceQosPolicy

name : string

QosPolicy

access_scope : PresentationQosPolicyAccessScopeKindcoherent_access : booleanordered_access : boolean

PresentationQosPolicy

ReaderDataLifecycleQosPolicy

autopurge_nowriter_samples_delay : Duration_tautopurge_disposed_samples_delay : Duration_t

enable_invalid_samples : booleaninvalid_sample_visibility : InvalidSampleVisibilityQosPolicy

autopurge_dispose_all : boolean

61API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

that the specification for QosPolicy follows the requested/offered (RxO) patternwhile trying to maintain the desirable decoupling of publication and subscription asmuch as possible. In this pattern:• the requesting side can specify a “requested” attribute for a particular QosPolicy• the offering side specifies an “offered” attribute for that QosPolicy.The Data Distribution Service will then determine whether the attribute requestedby the requesting side is compatible with what is offered by the offering side. Onlywhen the two QosPolicy settings are compatible, communication is established. Ifthe two QosPolicy settings are not compatible, the Data Distribution Service willnot establish communication between the two DDS_Entity objects and notify thisfact by means of the DDS_OFFERED_INCOMPATIBLE_QOS status on the offeringside and the DDS_REQUESTED_INCOMPATIBLE_QOS status on the requesting side.The application can detect this fact by means of a Listener or DDS_Condition.The interface description of these QosPolicys are as follows:

/* * struct DDS_<DDS_Entity>Qos * see appendix *//* * struct DDS_<name>QosPolicy */

struct DDS_UserDataQosPolicy { DDS_sequence_octet value; };struct DDS_TopicDataQosPolicy { DDS_sequence_octet value; };struct DDS_GroupDataQosPolicy { DDS_sequence_octet value; };struct DDS_TransportPriorityQosPolicy { DDS_long value; };struct DDS_LifespanQosPolicy { DDS_Duration_t duration; };enum DDS_DurabilityQosPolicyKind { DDS_VOLATILE_DURABILITY_QOS, DDS_TRANSIENT_LOCAL_DURABILITY_QOS, DDS_TRANSIENT_DURABILITY_QOS, DDS_PERSISTENT_DURABILITY_QOS };struct DDS_DurabilityQosPolicy { DDS_DurabilityQosPolicyKind kind; };enum DDS_PresentationQosPolicyAccessScopeKind { DDS_INSTANCE_PRESENTATION_QOS, DDS_TOPIC_PRESENTATION_QOS, DDS_GROUP_PRESENTATION_QOS };struct DDS_PresentationQosPolicy { DDS_PresentationQosPolicyAccessScopeKind

access_scope;

62API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

DDS_boolean coherent_access; DDS_boolean ordered_access; };struct DDS_DeadlineQosPolicy { DDS_Duration_t period; };struct DDS_LatencyBudgetQosPolicy { DDS_Duration_t duration; };enum DDS_OwnershipQosPolicyKind { DDS_SHARED_OWNERSHIP_QOS, DDS_EXCLUSIVE_OWNERSHIP_QOS };struct DDS_OwnershipQosPolicy { DDS_OwnershipQosPolicyKind kind; };struct DDS_OwnershipStrengthQosPolicy { DDS_long value; };enum DDS_LivelinessQosPolicyKind { DDS_AUTOMATIC_LIVELINESS_QOS, DDS_MANUAL_BY_PARTICIPANT_LIVELINESS_QOS, DDS_MANUAL_BY_TOPIC_LIVELINESS_QOS };struct DDS_LivelinessQosPolicy { DDS_LivelinessQosPolicyKind kind; DDS_Duration_t lease_duration; };struct DDS_TimeBasedFilterQosPolicy { DDS_Duration_t minimum_separation; };struct DDS_PartitionQosPolicy { DDS_StringSeq name; };enum DDS_ReliabilityQosPolicyKind { DDS_BEST_EFFORT_RELIABILITY_QOS, DDS_RELIABLE_RELIABILITY_QOS };struct DDS_ReliabilityQosPolicy { DDS_ReliabilityQosPolicyKind kind; DDS_Duration_t max_blocking_time; DDS_boolean synchronous; };enum DDS_DestinationOrderQosPolicyKind { DDS_BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS, DDS_BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS };struct DDS_DestinationOrderQosPolicy { DDS_DestinationOrderQosPolicyKind kind; };enum DDS_HistoryQosPolicyKind { DDS_KEEP_LAST_HISTORY_QOS, DDS_KEEP_ALL_HISTORY_QOS };struct DDS_HistoryQosPolicy { DDS_HistoryQosPolicyKind kind; DDS_long depth; };struct DDS_ResourceLimitsQosPolicy { DDS_long max_samples; DDS_long max_instances; DDS_long max_samples_per_instance; };struct DDS_EntityFactoryQosPolicy { DDS_boolean autoenable_created_entities; };struct DDS_WriterDataLifecycleQosPolicy { DDS_boolean autodispose_unregistered_instances; };

63API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

enum DDS_InvalidSampleVisibilityQosPolicyKind { DDS_NO_INVALID_SAMPLES, DDS_MINIMUM_INVALID_SAMPLES, DDS_ALL_INVALID_SAMPLES };struct DDS_InvalidSampleVisibilityQosPolicy { DDS_InvalidSampleVisibilityQosPolicyKind kind; };struct DDS_ReaderDataLifecycleQosPolicy { DDS_Duration_t autopurge_nowriter_samples_delay; DDS_Duration_t autopurge_disposed_samples_delay; DDS_boolean autopurge_dispose_all; DDS_boolean enable_invalid_samples; /* deprecated */ DDS_InvalidSampleVisibilityQosPolicy

invalid_sample_visibility; };struct DurabilityServiceQosPolicy { DDS_Duration_t service_cleanup_delay; DDS_HistoryQosPolicyKind history_kind; DDS_long history_depth; DDS_long max_samples; DDS_long max_instances; DDS_long max_samples_per_instance; };enum DDS_SchedulingClassQosPolicyKind { DDS_SCHEDULE_DEFAULT, DDS_SCHEDULE_TIMESHARING, DDS_SCHEDULE_REALTIME };struct DDS_SchedulingClassQosPolicy { DDS_SchedulingClassQosPolicyKind kind; };enum DDS_SchedulingPriorityQosPolicyKind { DDS_PRIORITY_RELATIVE, DDS_PRIORITY_ABSOLUTE };struct DDS_SchedulingPriorityQosPolicy { DDS_SchedulingPriorityQosPolicyKind kind; };struct DDS_SchedulingQosPolicy { DDS_SchedulingClassQosPolicy scheduling_class; DDS_SchedulingPriorityQosPolicy scheduling_priority_kind; DDS_long scheduling_priority; };struct DDS_SubscriptionKeyQosPolicy { DDS_boolean use_key_list, DDS_StringSeq key_list };struct DDS_ReaderLifespanQosPolicy { DDS_boolean use_lifespan, DDS_Duration_t duration };struct DDS_ShareQosPolicy { DDS_string name, DDS_boolean enable };struct DDS_ViewKeyQosPolicy { DDS_boolean use_key_list; DDS_StringSeq key_list };

/* * implemented API operations * <no operations>

64API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

*/

Default attributesThe default attributes of each QosPolicy are listed in Table 5: below.:

Table 5: QosPolicy Default Attributes

QosPolicy Attribute Valueuser_data value.length 0

topic_data value.length 0

group_data value.length 0

transport_priority value 0

lifespan duration DDS_DURATION_INFINITE

durability kind DDS_VOLATILE_DURABILITY_QOS

presentation access_scope DDS_INSTANCE_PRESENTATION_QOS

coherent_access FALSE

ordered_access FALSE

deadline period DDS_DURATION_INFINITE

latency_budget duration 0

ownership_strength value 0

ownership kind DDS_SHARED_OWNERSHIP_QOS

liveliness kind DDS_AUTOMATIC_LIVELINESS_QOS

lease_duration DDS_DURATION_INFINITE

time_based_filter minimum_separation 0

partition name.length 0

reliability kind DDS_BEST_EFFORT_RELIABILITY_QOS

max_blocking_time 100 ms

synchronous FALSE

destination_order kind DDS_BY_RECEPTION_ TIMESTAMP_DESTINATIONORDER_QOS

history kind DDS_KEEP_LAST_HISTORY_QOS

depth 1

resource_limits max_samples DDS_LENGTH_UNLIMITED

max_instances DDS_LENGTH_UNLIMITED

max_samples_ per_instance DDS_LENGTH_UNLIMITED

entity_factory autoenable_ created_entities

TRUE

writer_data_lifecycle autodispose_unregistered_instances

TRUE

65API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

RxOThe QosPolicy settings that need to be set in a compatible manner between thepublisher and subscriber ends are indicated by the setting of the “RxO”(Requested/Offered) property. The “RxO” property of each QosPolicy is listed inTable 6: on page 67• A “RxO” setting of “Yes” indicates that the QosPolicy can be set at both ends

(publishing and subscribing) and the attributes must be set in a compatiblemanner. In this case the compatible attributes are explicitly defined

reader_data_lifecycle autopurge_ nowriter_samples_delay

DDS_DURATION_INFINITE

autopurge_ disposed_samples_delay

DDS_DURATION_INFINITE

autopurge_dispose_all FALSE

enable_invalid_samples TRUE

invalid_sample_visibility.kind

DDS_MINIMUM_INVALID_SAMPLES

durability_service history_kind KEEP_LAST

history_depth 1

max_samples LENGTH_UNLIMITED

max_instances LENGTH_UNLIMITED

max_samples_ per_instance LENGTH_UNLIMITED

service_cleanup_delay 0

watchdog_scheduling,listener_scheduling

scheduling_class.kind DDS_SCHEDULE_DEFAULT

scheduling_priority_kind.kind

DDS_PRIORITY_RELATIVE

scheduling_priority 0

subscription_keys use_key_list FALSE

key_list.length 0

reader_lifespan use_lifespan FALSE

duration DDS_DURATION_INFINITE

share name ""

enable FALSE

view_keys use_key_list FALSE

key_list.length 0

Table 5: QosPolicy Default Attributes (continued)

QosPolicy Attribute Value

66API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

• A “RxO” setting of “No” indicates that the QosPolicy can be set at both ends(publishing and subscribing) but the two settings are independent. That is, allcombinations of attributes are compatible

• A “RxO” setting of “Not applicable” indicates that the QosPolicy can only bespecified at either the publishing or the subscribing end, but not at both ends. Socompatibility does not apply.

ChangeableThe “changeable” property determines whether the QosPolicy can be changedafter the DDS_Entity is enabled. In other words, a QosPolicy with “changeable”setting of “No” is considered “immutable” and can only be specified either atDDS_Entity creation time or prior to calling the DDS_Entity_enable operationon the DDS_Entity.When the application tries to change a QosPolicy with “changeable” setting of“No”, the Data Dis t r ibut ion Service wi l l no t i fy th is by re turning aDDS_RETCODE_IMMUTABLE_POLICY.The basic way to modify or set the <DDS_Entity>Qos is by using aDDS_<Entity>_get_qos and DDS_<Entity>_set_qos operation to get allQosPolicy settings from this DDS_Entity (that is the <DDS_Entity>Qos),modify several specific QosPolicy settings and put them back using an useroperation to set all QosPolicy settings on this DDS_Entity (that is the<DDS_Entity>Qos). An example of these operations for the DDS_DataWriterare DDS_DataWriter_get_qos and DDS_DataWriter_set_qos, which takethe DataWriterQos as a parameter.The “RxO” setting and the “changeable” setting of each QosPolicy are listed inTable 6: below:

Table 6: QosPolicy Basics

QosPolicy Concerns DDS_Entity RxO Changeable After

Enablinguser_data DDS_DomainParticipant

DDS_DataReaderDDS_DataWriter

No Yes

topic_data DDS_Topic No Yesgroup_data DDS_Publisher

DDS_SubscriberNo Yes

transport_priority DDS_TopicDDS_DataWriter

Not applicable Yes

67API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

lifespan DDS_TopicDDS_DataWriter

Not applicable Yes

durability DDS_TopicDDS_DataReaderDDS_DataWriter

Yes No

presentation DDS_PublisherDDS_Subscriber

Yes No

deadline DDS_TopicDDS_DataReaderDDS_DataWriter

Yes Yes

latency_budget DDS_TopicDDS_DataReaderDDS_DataWriter

Yes Yes

ownership DDS_TopicDDS_DataReaderDDS_DataWriter

Yes No

ownership_strength DDS_DataWriter Not applicable Yesliveliness DDS_Topic

DDS_DataReaderDDS_DataWriter

Yes No

time_based_filter DDS_DataReader Not applicable Yespartition DDS_Publisher

DDS_SubscriberNo Yes

reliability DDS_TopicDDS_DataReaderDDS_DataWriter

Yes No

destination_order DDS_TopicDDS_DataReaderDDS_DataWriter

Yes No

history DDS_TopicDDS_DataReaderDDS_DataWriter

No No

resource_limits DDS_TopicDDS_DataReaderDDS_DataWriter

No No

Table 6: QosPolicy Basics (continued)

QosPolicy Concerns DDS_Entity RxO Changeable After

Enabling

68API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

The next paragraphs describe the usage of each QosPolicy struct.

3.1.3.1 DDS_DeadlineQosPolicy

Synopsis#include <dds_dcps.h>

struct DDS_DeadlineQosPolicy { DDS_Duration_t period; };

DescriptionThis QosPolicy defines the period within which a new sample is expected by theDataReader or to be written by the DataWriter.

AttributesDDS_Duration_t period - specifies the period within which a new sample is

expected or to be written.

Detailed DescriptionThis QosPolicy will set the period within which a DDS_DataReader expects anew sample or, in case of a DDS_DataWriter, the period in which it expectsapplications to write the sample. The default value of the period isDDS_DURATION_INFINITE, indicating that there is no deadline. The QosPolicy

entity_factory DDS_DomainParticipantFactoryDDS_DomainParticipantDDS_PublisherDDS_Subscriber

No Yes

writer_data_lifecycle DDS_DataWriter Not applicable Yesreader_data_lifecycle DDS_DataReader Not applicable Yesdurability_service DDS_Topic No Noscheduling DDS_DomainParticipant Not applicable Nosubscription_keys DDS_DataReader Not applicable Noreader_lifespan DDS_DataReader Not applicable Yesshare DDS_DataReader

DDS_SubscriberNot applicable No

Noview_keys DDS_DataReaderView Not applicable No

Table 6: QosPolicy Basics (continued)

QosPolicy Concerns DDS_Entity RxO Changeable After

Enabling

69API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

may be used to monitor the real-time behaviour, a DDS_Listener or aDDS_StatusCondition may be used to catch the event that is generated when adeadline is missed.DDS_DeadlineQosPolicy is instance oriented (i.e. the period is monitored foreach individual instance).The exact consequences of a missed deadline depend on the DDS_Entity in whichit occured, and the DDS_OwnershipQosPolicy value of that DDS_Entity:• In case a DDS_DataWriter misses an instance deadline (regardless of itsDDS_OwnershipQosPolicy setting), anoffered_deadline_missed_status is raised, which can be detected byeither a DDS_Listener or a DDS_StatusCondition. There are no furtherconsequences.

• In case a DDS_DataReader misses an instance deadline, arequested_deadline_missed_status is raised, which can be detected byeither a DDS_Listener or a DDS_StatusCondition. In case theDDS_OwnershipQosPolicy is set to SHARED, there are no furtherconsequences. In case the DDS_OwnershipQosPolicy is set to EXCLUSIVE, theownership of that instance on that particular DDS_DataReader is transferred tothe next available highest strength DDS_DataWriter, but this will have noimpact on the instance_state whatsoever. So even when a deadline is missedfor an instance that has no other (lower-strength) DDS_DataWriters to transferownership to, the instance_state remains unchanged. See also Section3.1.3.11, DDS_OwnershipQosPolicy.

This QosPolicy is applicable to a DDS_DataReader, a DDS_DataWriter and aDDS_Topic. After enabling of the concerning DDS_Entity, this QosPolicy maybe changed by using the DDS_<DDS_Entity>_set_qos operation.

Requested/OfferedIn case the Requested/Offered QosPolicy are incompatible, the notificationDDS_OFFERED_INCOMPATIBLE_QOS s ta tus on the offer ing s ide andDDS_REQUESTED_INCOMPATIBLE_QOS status on the requesting side is raised.

Table 7: DDS_DeadlineQosPolicy

Period Compatibilityoffered period < requested period compatibleoffered period = requested period compatibleoffered period > requested period INcompatible

70API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

Whether communication is established, is controlled by the Data DistributionService, depending on the Requested/Offered QosPolicy of the DDS_DataWriterand DDS_DataReader. In other words, the communication between anyDDS_DataWriter and DDS_DataReader depends on what is expected by theDDS_DataReader. As a consequence, a DDS_DataWriter that has anincompatible QoS with respect to what a DDS_DataReader specifies is not allowedto send its data to that specific DDS_DataReader. A DDS_DataReader that has anincompatible QoS with respect to what a DDS_DataWriter specifies does not getany data from that particular DDS_DataWriter.Changing an existing deadline period using the set_qos operation on either theDDS_DataWriter or DDS_DataReader may have consequences for theconnectivity between readers and writers, depending on their RxO values. (See alsoin Section 3.1.3, Struct QosPolicy, the paragraph entitled Requested/Offered.)Consider a writer with deadline period Pw and a reader with deadline period Pr,where Pw <= Pr. In this case a connection between that reader and that writer isestablished. Now suppose Pw is changed so that Pw > Pr, then the existingconnection between reader and writer will be lost, and the reader will behave as ifthe writer unregistered all its instances, transferring the ownership of these instanceswhen appropriate. See also Section 3.1.3.11, DDS_OwnershipQosPolicy.

DDS_TopicQosThis QosPolicy can be set on a DDS_Topic. The DDS_DataWriter and/orDDS_DataReader c a n c opy t h i s qos by u s i n g t h e o p e r a t i o n sDDS_<DDS_Entity>_copy_from_topic_qos and t he nDDS_<DDS_Entity>_set_qos. That way the application can relatively easilyensure the QosPolicy fo r the DDS_Topic , DDS_DataReader andDDS_DataWriter are consistent.

3.1.3.2 DDS_DestinationOrderQosPolicy

Synopsis#include <dds_dcps.h>

enum DDS_DestinationOrderQosPolicyKind { DDS_BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS, DDS_BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS };struct DDS_DestinationOrderQosPolicy { DDS_DestinationOrderQosPolicyKind kind; };

DescriptionThis QosPolicy controls the order in which the DDS_DataReader stores the data.

71API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

AttributesDDS_DestinationOrderQosPolicyKind kind - controls the order in which

the DDS_DataReader stores the data.

Detailed DescriptionThis QosPolicy controls the order in which the DDS_DataReader stores the data.The order of storage is controlled by the timestamp. However a choice can be madeto use the timestamp of the DDS_DataReader (time of reception) or the timestampof the DDS_DataWriter (source timestamp).This QosPolicy is applicable to a DDS_DataWriter, DDS_DataReader and aDDS_Topic. After enabling of the concerning DDS_Entity, this QosPolicy cannotbe changed any more.

AttributeThe QosPolicy is controlled by the attribute kind which may be:• DDS_BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS• DDS_BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOSWhen set to DDS_BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS, theorder is based on the timestamp, at the moment the sample was received by theDDS_DataReader. When set to DDS_BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS, the orderis based on the timestamp, which was set by the DDS_DataWriter. This means thatthe system needs some time synchronisation.

Requested/OfferedIn case the Requested/Offered QosPolicy are incompatible, the notificationDDS_OFFERED_INCOMPATIBLE_QOS s ta tus on the offer ing s ide andDDS_REQUESTED_INCOMPATIBLE_QOS status on the requesting side is raised.

Whether communication is established, is controlled by the Data DistributionService, depending on the Requested/Offered QosPolicy of the DDS_DataWriterand DDS_DataReader. In other words, the communication between anyDDS_DataWriter and DDS_DataReader depends on what is expected by the

Table 8: Requested/Offered DDS_DestinationOrderQosPolicy

BY_RECEPTION_TIMESTAMP

BY_SOURCE_TIMESTAMP

BY_RECEPTION_TIMESTAMP compatible INcompatibleBY_SOURCE_TIMESTAMP compatible compatible

OfferedRequested

72API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

DDS_DataReader. As a consequence, a DDS_DataWriter that has anincompatible QoS with respect to what a DDS_DataReader specified, is notallowed to send its data to that specific DDS_DataReader. A DDS_DataReaderthat has an incompatible QoS with respect to what a DDS_DataWriter specified,does not get any data from that particular DDS_DataWriter.

DDS_TopicQosThis QosPolicy can be set on a DDS_Topic. The DDS_DataWriter and/orDDS_DataReader c a n c opy t h i s qos by u s i n g t h e o p e r a t i o n sDDS_<DDS_Entity>_copy_from_topic_qos and t he nDDS_<DDS_Entity>_set_qos. That way the application can relatively easilyensure the QosPolicy fo r the DDS_Topic , DDS_DataReader andDDS_DataWriter are consistent.

3.1.3.3 DDS_DurabilityQosPolicy

Synopsis#include <dds_dcps.h>

enum DDS_DurabilityQosPolicyKind { DDS_VOLATILE_DURABILITY_QOS, DDS_TRANSIENT_LOCAL_DURABILITY_QOS, DDS_TRANSIENT_DURABILITY_QOS, DDS_PERSISTENT_DURABILITY_QOS };struct DDS_DurabilityQosPolicy { DDS_DurabilityQosPolicyKind kind; };

DescriptionThis QosPolicy controls whether the data should be stored for late joining readers.

AttributesDDS_DurabilityQosPolicyKind kind - specifies the type of durability from

DDS_VOLATILE_DURABILITY_QOS (short life) toDDS_PERSISTENT_DURABILITY_QOS (long life).

Detailed DescriptionThe decoupling between DDS_DataReader and DDS_DataWriter offered by theData Distribution Service allows an application to write data even if there are nocurrent readers on the network. Moreover, a DDS_DataReader that joins thenetwork after some data has been written could potentially be interested in accessingthe most current values of the data as well as some history. This QosPolicycontrols whether the Data Distribution Service will actually make data available tolate-joining DDS_DataReaders.

73API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

This QosPolicy is applicable to a DDS_DataReader, DDS_DataWriter andDDS_Topic. After enabling of the concerning DDS_Entity, this QosPolicycannot be changed any more.

AttributesThe QosPolicy is controlled by the attribute kind which may be:• DDS_VOLATILE_DURABILITY_QOS - the samples are not available to

late-joining DDS_DataReaders. In other words, only DDS_DataReaders,which were present at the time of the writing and have subscribed to thisDDS_Topic, will receive the sample. When a DDS_DataReader subscribesafterwards (late-joining), it will only be able to read the next written sample. Thissetting is typically used for data, which is updated quickly;

• DDS_TRANSIENT_LOCAL_DURABILITY_QOS - currently behaves identically tothe TRANSIENT_DURABILITY_QOS, except for its RxO properties. The desiredbehaviour of TRANSIENT_LOCAL_DURABILITY_QOS can be achieved from theTRANSIENT_DURABILITY_QOS with the default (TRUE) setting of theautodispose_unregistered_instances flag on the DataWriter and theservice_cleanup_delay set to 0 on the durability service. This is because forTRANSIENT_LOCAL, the data should only remain available for late-joiningreaders during the lifetime of its source writer, so it is not required to survive afterits source writer has been deleted. Since the deletion of a writer implicitlyunregisters all its instances, an autodispose_unregistered_instancesvalue of TRUE will also dispose the affected data from the durability store, andthus prevent it from remaining available to late-joining readers.

• DDS_TRANSIENT_DURABILITY_QOS - some samples are available to late-joiningDDS_DataReaders (stored in memory). This means that the late-joiningDDS_DataReaders are able to read these previously written samples. TheDDS_DataReader does not necessarily have to exist at the time of writing. Notall samples are stored (depending on QosPolicy History and QosPolicyresource_limits). The storage does not depend on the DDS_DataWriter andwill outlive the DDS_DataWriter. This may be used to implement reallocation ofapplications because the data is saved in the Data Distribution Service (not in theDDS_DataWriter). This setting is typically used for state related information ofan application. In this case also the DurabilityServiceQosPolicy settingsare relevant for the behaviour of the Data Distribution Service;

• DDS_PERSISTENT_DURABILITY_QOS - the data is stored in permanent storage(e.g. hard disk). This means that the samples are also available after a systemrestart. The samples not only outlives the DDS_DataWriters, but even the DataDistribution Service and the system. This setting is typically used for attributes

74API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

and settings for an application or the system. In this case also theDurabilityServiceQosPolicy settings are relevant for the behaviour of theData Distribution Service.

Requested/OfferedIn case the Requested/Offered QosPolicy are incompatible, the notificationDDS_OFFERED_INCOMPATIBLE_QOS s ta tus on the offer ing s ide andDDS_REQUESTED_INCOMPATIBLE_QOS status on the requesting side is raised.

This means that the Request/Offering mechanism is applicable between:• the DDS_DataWriter and the DDS_DataReader: if the QosPolicy settings

between DDS_DataWriter and DDS_DataReader are inconsistent, nocommunication between them is established. In addition the DDS_DataWriterwill be informed via a DDS_REQUESTED_INCOMPATIBLE_QOS status change andthe DDS_DataReader will be informed via anDDS_OFFERED_INCOMPATIBLE_QOS status change

• the DDS_DataWriter and the Data Distribution Service (as a built-inDDS_DataReader): if the QosPolicy settings between DDS_DataWriter andthe Data Distribution Service are inconsistent, no communication between them isestablished. In that case data published by the DDS_DataWriter will not bemaintained by the service and as a consequence will not be available for latejoining DDS_DataReaders. The QosPolicy of the Data Distribution Service inthe role of DDS_DataReader is specified by the DDS_Topic QosPolicy

• the Data Distribution Service (as a built-in DDS_DataWriter) and theDDS_DataReader: if the QosPolicy settings between the Data DistributionService and the DDS_DataReader are inconsistent, no communication betweenthem is established. In that case the Data Distribution Service will not publishhistorical data to late joining DDS_DataReaders. The QosPolicy of the DataDistribution Service in the role of DDS_DataWriter is specified by theDDS_Topic QosPolicy.

Table 9: Requested/Offered DDS_DurabilityQosPolicy

VOLATILE TRANSIENT_ LOCAL

TRANSIENT PERSISTENT

VOLATILE compatible INcompatible INcompatible INcompatibleTRANSIENT_LOCAL compatible compatible INcompatible INcompatibleTRANSIENT compatible compatible compatible INcompatiblePERSISTENT compatible compatible compatible compatible

OfferedRequested

75API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

CleanupThe DDS_DurabilityQosPolicy kind se t t ing DDS_TRANSIENT_LOCAL_DURABILITY_QOS , DDS_TRANSIENT_DURABILITY_QOS andDDS_PERSISTENT_DURABILITY_QOS de t e rm in e t h a t t h eDDS_DurabilityServiceQosPolicy applies for the DDS_Topic. It controlsamongst others at which time the durability service is allowed to remove allinformation regarding a data-instance. Information on a data-instance is maintaineduntil the following conditions are met:• the instance has been explicitly disposed of (instance_state =DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE),

• and the system detects that there are no more “live” DDS_DataWriter objectswriting the instance, that is, all DDS_DataWriter eitherunregister_instance the instance (callDDS_DataWriter_unregister_instance operation) or lose theirliveliness,

• and a time interval longer than service_cleanup_delay has elapsed since themoment the Data Distribution Service detected that the previous two conditionswere met.

The u s e o f t he DDS_DurabilityServiceQosPolicy a t t r i b u t eservice_cleanup_delay is apparent in the situation where an applicationdisposes of an instance and it crashes before having a chance to completeadditional tasks related to the disposition. Upon re-start the application may ask fori n i t i a l d a t a t o r e g a i n i t s s t a t e a n d t h e d e l a y in t r o d u c e d b y t h eservice_cleanup_delay allows the re-started application to receive theinformation on the disposed of instance and complete the interrupted tasks.

DDS_TopicQosThis QosPolicy can be set on a DDS_Topic. The DDS_DataWriter and/orDDS_DataReader c a n c op y t h i s qo s b y u s i ng t he op e r a t i on sDDS_<DDS_Entity>_copy_from_topic_qos and t he nDDS_<DDS_Entity>_set_qos. That way the application can relatively easilyensure the QosPolicy fo r the DDS_Topic , DDS_DataReader andDDS_DataWriter are consistent.

3.1.3.4 DDS_DurabilityServiceQosPolicy

ScopeDDS

Synopsis#include <dds_dcps.h>

76API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

struct DDS_DurabilityServiceQosPolicy { DDS_Duration_t service_cleanup_delay; DDS_HistoryQosPolicyKind history_kind; DDS_long history_depth; DDS_long max_samples; DDS_long max_instances; DDS_long max_samples_per_instance; };

DescriptionThis QosPolicy controls the behaviour of the durability service regarding transientand persistent data.

AttributesDDS_Duration_t service_cleanup_delay - specifies how long the durability

service must wait before it is allowed to remove the information on the transientor persistent topic data-instances as a result of incoming dispose messages.

DDS_HistoryQosPolicyKind history_kind - specifies the type of history,w h i c h m a y b e DDS_KEEP_LAST_HISTORY_QOS , o rDDS_KEEP_ALL_HISTORY_QOS the durability service must apply for thetransient or persistent topic data-instances.

DDS_long history_depth - specifies the number of samples of each instance ofdata (identified by its key) that is managed by the durability service for thetransient or persis tent topic data-instances. If history_kind i sKEEP_LAST_HISTORY_QOS, history_depth must be smaller than or equal tomax_samples_per_instance for this QosPolicy to be consistent.

DDS_long max_samples - specifies the maximum number of data samples for allinstances the durability service will manage for the transient or persistent topicdata-instances.

DDS_long max_instances - specifies the maximum number of instances thedurability service will manage for the transient or persistent topicdata-instances.

DDS_long max_samples_per_instance - specifies the maximum number ofsamples of any single instance the durability service will manage for thetransient or persistent topic data-instances. If history_kind is DDS_KEEP_LAST_HISTORY_QOS, max_samples_per_instance must be greater than or equalto history_depth for this QosPolicy to be consistent.

77API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

Detailed DescriptionThis QosPolicy controls the behaviour of the durability service regarding transientand persistent data. It controls for the transient or persistent topic; the time at whichinformation regarding the topic may be discarded, the history policy it must set andthe resource limits it must apply.

CleanupThe setting of the DDS_DurabilityServiceQosPolicy only applies when kindof t he DDS_DurabilityQosPolicy i s e i t h e r DDS_TRANSIENT_DURABILITY_QOS o r DDS_PERSISTENT_DURABILITY_QOS . T h eservice_cleanup_delay setting controls at which time the durability service isallowed to remove all information regarding a data-instance. Information on adata-instance is maintained until the following conditions are met:• the instance has been explicitly disposed of (instance_state =DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE)

• and the system detects that there are no more “live” DataWriter objects writingthe instance, that is, all DataWriter either unregister_instance theinstance (call unregister_instance operation) or lose their liveliness

• and a time interval longer than service_cleanup_delay has elapsed since themoment the Data Distribution Service detected that the previous two conditionswere met

The use of the attribute service_cleanup_delay is apparent in the situationwhere an application disposes an instance and it crashes before having a chanceto complete additional tasks related to the disposal of the instance. Upon re-startthe application may ask for initial data to regain its state and the delay introduced bythe service_cleanup_delay allows the re-started application to receive theinformation of the disposed instance and complete the interrupted tasks.

HistoryThe attributes history_kind and history_depth apply to the history settings ofthe durability service’s internal DDS_DataWriter and DDS_DataReadermanaging the topic. The DDS_HistoryQosPolicy behaviour, as described inSection 3.1.3.7, DDS_HistoryQosPolicy, applies to these attributes.

Resource LimitsThe at t r ibutes max_samples , max_instances and max_samples_per_instance apply to the resource limits of the durability service’s internalDDS_DataWriter and DDS_DataReader managing the top ic . TheDDS_ResourceLimitsQosPolicy behaviour, as described in paragraph 3.1.3.17(DDS_ResourceLimitsQosPolicy) applies to these attributes.

78API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

TopicQosThis QosPolicy can be set on a DDS_Topic only. After enabling of the concerningDDS_Topic, this QosPolicy can not be changed any more.

3.1.3.5 DDS_EntityFactoryQosPolicy

Synopsis#include <dds_dcps.h>

struct DDS_EntityFactoryQosPolicy { DDS_boolean autoenable_created_entities; };

DescriptionThis QosPolicy controls the behaviour of the Entity as a factory for otherentities.

AttributesDDS_boolean autoenable_created_entities - specifies whether the entity

acting as a factory automatically enables the instances it creates. Ifautoenable_created_entities is TRUE the factory will automatically enable eachcreated Entity, otherwise it will not.

Detailed DescriptionThis QosPolicy controls the behaviour of the Entity as a factory for otherentities. It concerns only DDS_DomainParticipantFactory (as factory forDDS_DomainParticipant), DDS_DomainParticipant (as factory forDDS_Publisher, DDS_Subscriber, and DDS_Topic), DDS_Publisher (asfactory for DDS_DataWriter), and DDS_Subscriber (as factory forDDS_DataReader).This policy is mutable. A change in the policy affects only the entities created afterthe change; not the previously created entities.The setting of autoenable_created_entities to TRUE indicates that thefactory create_<entity> operation will automatically invoke the enableoperation each time a new DDS_Entity is created. Therefore, the DDS_Entityreturned by create_<entity> will already be enabled. A setting of FALSEindicates that the DDS_Entity will not be automatically enabled: the applicationwill need to enable it explicitly by means of the enable operation. See Section3.1.1.1, DDS_Entity_enable for a detailed description about the differences betweenenabled and disabled entities. The default setting of autoenable_created_entities is TRUE meaning that bydefault it is not necessary to explicitly call enable on newly-created entities.

79API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

3.1.3.6 DDS_GroupDataQosPolicy

Synopsis#include <dds_dcps.h>

struct DDS_GroupDataQosPolicy { DDS_sequence_octet value; };

DescriptionThis QosPolicy allows the application to attach additional information to aDDS_Publisher or DDS_Subscriber DDS_Entity. This information isdistributed with the DDS_BuiltinTopics.

AttributesDDS_sequence_octet value - a sequence of octets that holds the application

group data. By default, the sequence has length 0.

Detailed DescriptionThis QosPolicy allows the application to attach additional information to aDDS_Publisher or DDS_Subscriber DDS_Entity. This information isdistributed with the DDS_BuiltinTopic. An application that discovers a newDDS_Entity of the listed kind, can use this information to add additionalfunctionality. The DDS_GroupDataQosPolicy is changeable and updates of theDDS_BuiltinTopic instance must be expected. Note that the Data DistributionService is not aware of the real structure of the group data (the Data DistributionSystem handles it as an opaque type) and that the application is responsible forcorrect mapping on structural types for the specific platform.

3.1.3.7 DDS_HistoryQosPolicy

Synopsis#include <dds_dcps.h>

enum DDS_HistoryQosPolicyKind { DDS_KEEP_LAST_HISTORY_QOS, DDS_KEEP_ALL_HISTORY_QOS };struct DDS_HistoryQosPolicy { DDS_HistoryQosPolicyKind kind; DDS_long depth; };

DescriptionThis QosPolicy controls which samples will be stored when the value of aninstance changes (one or more times) before it is finally communicated.

80API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

AttributesDDS_HistoryQosPolicyKind kind - specifies the type of history, which may be

DDS_KEEP_LAST_HISTORY_QOS or DDS_KEEP_ALL_HISTORY_QOS.DDS_long depth - specifies the number of samples of each instance of data

(identified by its key) managed by this DDS_Entity.

Detailed DescriptionThis QosPolicy controls whether the Data Distribution Service should deliver onlythe most recent sample, attempt to deliver all samples, or do something in between.In other words, how the DDS_DataWriter or DDS_DataReader should storesamples. Normally, only the most recent sample is available but some history can bestored.

DDS_DataWriterOn the publishing side this QosPolicy controls the samples that should bemaintained by the DDS_DataWriter on behalf of existing DDS_DataReaderobjects. The behaviour with respect to a DDS_DataReader objects discovered aftera sample is written is controlled by the DDS_DurabilityQosPolicy.

DDS_DataReaderOn the subscribing side it controls the samples that should be maintained until theapplication “takes” them from the Data Distribution Service.This QosPolicy is applicable to a DDS_DataReader, DDS_DataWriter andDDS_Topic. After enabling of the concerning DDS_Entity, this QosPolicycannot be changed any more.

AttributesThe QosPolicy is controlled by the attribute kind which can be:• DDS_KEEP_LAST_HISTORY_QOS - the Data Distribution Service will only

attempt to keep the latest values of the instance and discard the older ones. Theattribute “depth” determines how many samples in history will be stored. Inother words, only the most recent samples in history are stored. On the publishingside, the Data Distribution Service will only keep the most recent “depth”samples of each instance of data (identified by its key) managed by theDDS_DataWriter. On the subscribing side, the DDS_DataReader will onlykeep the most recent “depth” samples received for each instance (identified byits key) until the application “takes” them via the DDS_DataReader_takeoperation. DDS_KEEP_LAST_HISTORY_QOS is the default kind. The defaultvalue of depth is 1, indicating that only the most recent value should bedelivered. If a depth other than 1 is specified, it should be compatible with thesettings of the DDS_ResourceLimitsQosPolicy max_samples_

81API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

per_instance. For these two QosPolicy settings to be compatible, they mustverify that depth <= max_samples_per_instance, otherwise aDDS_RETCODE_INCONSISTENT_POLICY is generated on relevant operations;

• DDS_KEEP_ALL_HISTORY_QOS - all samples are stored, provided, the resourcesare available. On the publishing side, the Data Distribution Service will attempt tokeep all samples (representing each value written) of each instance of data(identified by its key) managed by the DDS_DataWriter until they can bedelivered to all subscribers. On the subscribing side, the Data DistributionService will attempt to keep all samples of each instance of data (identified by itskey) managed by the DDS_DataReader. These samples are kept until theapplication “takes” them from the Data Distribution Service via theDDS_DataReader_take operation. The setting of depth has no effect. Itsimplied value is DDS_LENGTH_UNLIMITED. The resources that the DataDistribution Service can use to keep this history are limited by the settings of theDDS_ResourceLimitsQosPolicy. If the limit is reached, the behaviour of theData Distribution Service will depend on the DDS_ReliabilityQosPolicy. Ifthe DDS_ReliabilityQosPolicy is DDS_BEST_EFFORT_RELIABILITY_QOS, the old values are discarded. If DDS_ReliabilityQosPolicy isDDS_RELIABLE_RELIABILITY_QOS, the Data Distribution Service will blockthe DDS_DataWriter until it can deliver the necessary old values to allsubscribers.

On the subscribing side it controls the samples that should be maintained until theapplication “takes” them from the Data Distribution Service. On the publishing sidethis QosPolicy controls the samples that should be maintained by theDDS_DataWriter on behalf of DDS_DataReader objects. The behaviour withrespect to a DDS_DataReader objects discovered after a sample is written iscontrolled by the DDS_DurabilityQosPolicy. In more detail, this QosPolicyspecifies the behaviour of the Data Distribution Service in case the value of asample changes (one or more times) before it can be successfully communicated toone or more DDS_Subscribers.

Requested/OfferedThe setting of the QosPolicy offered is independent of the one requested, in otherwords they are never considered incompatible. The communication will not ber e j e c t e d o n a c c o u n t o f t h i s QosPolicy. T h e n o t i f i c a t i o nDDS_OFFERED_INCOMPATIBLE_QOS s t a tus on the offe r ing s ide orDDS_REQUESTED_INCOMPATIBLE_QOS status on the requesting side will not beraised.

82API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

DDS_TopicQosThis QosPolicy can be set on a DDS_Topic. The DDS_DataWriter and/orDDS_DataReader c a n c opy t h i s qos by u s i n g t h e o p e r a t i o n sDDS_<DDS_Entity>_copy_from_topic_qos and t he nDDS_<DDS_Entity>_set_qos. That way the application can relatively easilyensure the QosPolicy fo r the DDS_Topic , DDS_DataReader andDDS_DataWriter are consistent.

3.1.3.8 DDS_LatencyBudgetQosPolicy

Synopsis#include <dds_dcps.h>

struct DDS_LatencyBudgetQosPolicy { DDS_Duration_t duration; };

DescriptionSpecifies the maximum acceptable additional delay to the typical transport delayfrom the time the data is written until the data is delivered at the DDS_DataReaderand the application is notified of this fact.

AttributesDDS_Duration_t duration - specifies the maximum acceptable additional delay

from the time the data is written until the data is delivered.

Detailed DescriptionThis QosPolicy specifies the maximum acceptable additional delay to the typicaltransport delay from the time the data is written until the data is delivered at theDDS_DataReader and the application is notified of this fact. This QosPolicyprovides a means for the application to indicate to the Data Distribution Service the“urgency” of the data-communication. By having a non-zero duration the DataDistribution Service can optimise its internal operation. The default value of theduration is zero, indicating that the delay should be minimized.This QosPolicy is applicable to a DDS_DataReader, DDS_DataWriter andDDS_Topic. After enabling of the concerning DDS_Entity, this QosPolicy maybe changed by using the DDS_<DDS_Entity>_set_qos operation.

83API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

Requested/OfferedThis QosPolicy is considered a hint to the Data Distribution Service, which willautomatically adapt its behaviour to meet the requirements of the shortest delay ifpossible. In case the Requested/Offered QosPolicy are incompatible, thenotification DDS_OFFERED_INCOMPATIBLE_QOS status on the offering side andDDS_REQUESTED_INCOMPATIBLE_QOS status on the requesting side is raised.

Note that even when the offered duration is considered compatible to the requestedduration, this duration is not enforced in any way: there will be no notification onany violations of the requested duration.Changing an existing latency budget using the set_qos operation on either theDDS_DataWriter or DDS_DataReader may have consequences for theconnectivity between readers and writers, depending on their RxO values. (See alsoin Section 3.1.3, Struct QosPolicy the paragraph entitled Requested/Offered.)Consider a writer with budget Bw and a reader with budget Br, where Bw <= Br. Inthis case a connection between that reader and that writer is established. Nowsuppose Bw is changed so that Bw > Br, then the existing connection betweenreader and writer will be lost, and the reader will behave as if the writer unregisteredall its instances, transferring the ownership of these instances when appropriate. Seealso Section 3.1.3.11, DDS_OwnershipQosPolicy.

DDS_TopicQosThis QosPolicy can be set on a DDS_Topic. The DDS_DataWriter and/orDDS_DataReader c a n c op y t h i s qo s b y u s i ng t he op e r a t i on sDDS_<DDS_Entity>_copy_from_topic_qos and t he nDDS_<DDS_Entity>_set_qos. That way the application can relatively easilyensure the QosPolicy fo r the DDS_Topic , DDS_DataReader andDDS_DataWriter are consistent.

3.1.3.9 DDS_LifespanQosPolicy

Synopsis#include <dds_dcps.h>

struct DDS_LifespanQosPolicy { DDS_Duration_t duration; };

Table 10: DDS_LatencyBudgetQosPolicy

Duration Compatibilityoffered duration < requested duration compatibleoffered duration = requested duration compatibleoffered duration > requested duration INcompatible

84API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

DescriptionThis QosPolicy specifies the duration of the validity of the data written by theDDS_DataWriter.

AttributesDDS_Duration_t duration - specifies the length in time of the validity of the

data.

Detailed DescriptionThis QosPolicy specifies the duration of the validity of the data written by theDDS_DataWriter. When this time has expired, the data will be removed or if it hasnot been delivered yet, it will not be delivered at all. In other words, the durationis the time in which the data is still valid. This means that during this period aDDS_DataReader can access the data or if the data has not been delivered yet, its t i l l w i l l b e d e l i v e r e d . The d e f a u l t v a l u e o f t h e duration i sDDS_DURATION_INFINITE, indicating that the data does not expire.This QosPolicy is applicable to a DDS_DataWriter and a DDS_Topic. Afterenabling of the concerning DDS_Entity, this QosPolicy may be changed by usingthe DDS_<DDS_Entity>_set_qos operation.

Requested/OfferedThe setting of this QosPolicy is only applicable to the publishing side, in otherwords the Requested/Offered constraints are not applicable. The communicationwil l not be rejected on account of this QosPolicy. The notif icat ionDDS_OFFERED_INCOMPATIBLE_QOS status on the offering side will not be raised.

DDS_TopicQosThis QosPolicy can be set on a DDS_Topic. The DDS_DataWriter and/orDDS_DataReader c a n c opy t h i s qos by u s i n g t h e o p e r a t i o n sDDS_<DDS_Entity>_copy_from_topic_qos and t he nDDS_<DDS_Entity>_set_qos. That way the application can relatively easilyensure the QosPolicy fo r the DDS_Topic , DDS_DataReader andDDS_DataWriter are consistent.

3.1.3.10 DDS_LivelinessQosPolicy

Synopsis#include <dds_dcps.h>

enum DDS_LivelinessQosPolicyKind { DDS_AUTOMATIC_LIVELINESS_QOS, DDS_MANUAL_BY_PARTICIPANT_LIVELINESS_QOS, DDS_MANUAL_BY_TOPIC_LIVELINESS_QOS };

85API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

struct DDS_LivelinessQosPolicy { DDS_LivelinessQosPolicyKind kind; DDS_Duration_t lease_duration; };

DescriptionThis QosPolicy controls the way the liveliness of an DDS_Entity is beingreported.

AttributesDDS_LivelinessQosPolicyKind kind - controls the way the liveliness of an

DDS_Entity is reported.DDS_Duration_t lease_duration - specifies the duration of the interval

within which the liveliness must be reported.

Detailed DescriptionThis QosPolicy controls the way the liveliness of an DDS_Entity is beingdetermined. The l ivel iness must be reported per iodical ly before thelease_duration expires.This QosPolicy is applicable to a DDS_DataReader, a DDS_DataWriter and aDDS_Topic. After enabling of the concerning DDS_Entity, this QosPolicycannot be changed any more.

AttributesThe QosPolicy is controlled by the attribute kind which can be:• DDS_AUTOMATIC_LIVELINESS_QOS - the Data Distribution Service will take

care of reporting the Liveliness automatically with a rate determined by thelease_duration

• DDS_MANUAL_BY_PARTICIPANT_LIVELINESS_QOS - the application must takecare of reporting the liveliness before the lease_duration expires. If aDDS_Entity reports its liveliness, all DDS_Entities within the sameDDS_DomainParticipant that have their liveliness kind set toDDS_MANUAL_BY_PARTICIPANT_LIVELINESS_QOS, can be considered aliveby the Data Distribution Service. Liveliness can reported explicitly by calling theoperation DDS_DomainParticipant_assert_liveliness or implicitly bywriting some data

• DDS_MANUAL_BY_TOPIC_LIVELINESS_QOS - the application must take care ofreporting the liveliness before the lease_duration expires. This can explicitlybe done by calling the operation DDS_DataWriter_assert_liveliness orimplicitly by writing some data

86API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

The lease_duration specifies the duration of the interval within which theliveliness should be reported.

Requested/OfferedIn case the Requested/Offered QosPolicy are incompatible, the notificationDDS_OFFERED_INCOMPATIBLE_QOS s ta tus on the offer ing s ide andDDS_REQUESTED_INCOMPATIBLE_QOS status on the requesting side is raised.

Whether communication is established, is controlled by the Data DistributionService, depending on the Requested/Offered QosPolicy of the DDS_DataWriterand DDS_DataReader. In other words, the communication between anyDDS_DataWriter and DDS_DataReader depends on what is expected by theDDS_DataReader. As a consequence, a DDS_DataWriter that has anincompatible QoS with respect to what a DDS_DataReader specified is not allowedto send its data to that specific DDS_DataReader. A DDS_DataReader that has anincompatible QoS with respect to what a DDS_DataWriter specified does not getany data from that particular DDS_DataWriter.

DDS_TopicQosThis QosPolicy can be set on a DDS_Topic. The DDS_DataWriter and/orDDS_DataReader c a n c opy t h i s qos by u s i n g t h e o p e r a t i o n sDDS_<DDS_Entity>_copy_from_topic_qos and t he nDDS_<DDS_Entity>_set_qos. That way the application can relatively easilyensure the QosPolicy fo r the DDS_Topic , DDS_DataReader andDDS_DataWriter are consistent.

3.1.3.11 DDS_OwnershipQosPolicy

Synopsis#include <dds_dcps.h>

enum DDS_OwnershipQosPolicyKind { DDS_SHARED_OWNERSHIP_QOS, DDS_EXCLUSIVE_OWNERSHIP_QOS };struct DDS_OwnershipQosPolicy { DDS_OwnershipQosPolicyKind kind; };

Table 11: DDS_LivelinessQosPolicy

AUTOMATIC MANUAL_BY_PARTICIPANT

MANUAL_BY_TOPIC

AUTOMATIC compatible INcompatible INcompatibleMANUAL_BY_PARTICIPANT compatible compatible INcompatibleMANUAL_BY_TOPIC compatible compatible compatible

OfferedRequested

87API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

DescriptionThis QosPolicy specifies whether a DDS_DataWriter exclusively owns aninstance.

AttributesDDS_OwnershipQosPolicyKind kind - specifies whether a DDS_DataWriter

exclusively owns an instance.

Detailed DescriptionThis QosPolicy specifies whether a DDS_DataWriter exclusively may own aninstance. In other words, whether multiple DDS_DataWriter objects can write thesame instance at the same time. The DDS_DataReader objects will only read themodifications on an instance from the DDS_DataWriter owning the instance.Exclusive ownership is on an ins tance-by- instance basis . That is , aDDS_Subscriber c an r ece ive va lues wr i t t en by a lower s t r eng thDDS_DataWriter as long as they affect instances whose values have not beenwritten or registered by a higher-strength DDS_DataWriter.This QosPolicy is applicable to a DDS_DataReader, a DDS_DataWriter and aDDS_Topic. After enabling of the concerning DDS_Entity, this QosPolicycannot be changed any more.

AttributeThe QosPolicy is controlled by the attribute kind which can be:• DDS_SHARED_OWNERSHIP_QOS (default) - the same instance can be written by

multiple DDS_DataWriter objects. All updates will be made available to theDDS_DataReader objects. In other words it does not have a specific owner

• DDS_EXCLUSIVE_OWNERSHIP_QOS - the instance will only be accepted from oneDDS_DataWriter which is the only one whose modifications will be visible tothe DDS_DataReader objects

Requested/OfferedIn case the Requested/Offered QosPolicy are incompatible, the notificationOFFERED_INCOMPATIBLE_QOS s t a t u s o n t h e o f f e r i n g s i d e a n dREQUESTED_INCOMPATIBLE_QOS status on the requesting side is raised.

88API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

Whether communication is established, is controlled by the Data DistributionService, depending on the Requested/Offered QosPolicy of the DDS_DataWriterand DDS_DataReader. The value of the OWNERSHIP kind offered must exactlymatch the one requested or else they are considered incompatible. As aconsequence, a DDS_DataWriter that has an incompatible QoS with respect towhat a DDS_DataReader specified is not allowed to send its data to that specificDDS_DataReader. A DDS_DataReader that has an incompatible QoS with respectto what a DDS_DataWriter specified does not get any data from that particularDDS_DataWriter.

Exclusive OwnershipThe DDS_DataWriter with the highest DDS_OwnershipStrengthQosPolicyvalue and being alive (depending on the DDS_LivelinessQosPolicy) andwhich has not violated its DDS_DeadlineQosPolicy contract with respect to theinstance, will be considered the owner of the instance. Consequently, the ownershipcan change as a result of:• a DDS_DataWriter in the system with a higher value of theDDS_OwnershipStrengthQosPolicy modifies the instance

• a change in the DDS_OwnershipStrengthQosPolicy value (becomes less) ofthe DDS_DataWriter owning the instance

• a change in the liveliness (becomes not alive) of the DDS_DataWriter owningthe instance

• a deadline with respect to the instance that is missed by the DDS_DataWriterthat owns the instance.

Time-lineEach DDS_DataReader may detect the change of ownership at a different time. Inother words, at a particular point in time, the DDS_DataReader objects do not havea consistent picture of who owns each instance for that DDS_Topic. Outside thisgrey area in time all DDS_DataReader objects will consider the sameDDS_DataWriter to be the owner.

Table 12: Requested/Offered DDS_OwnershipQosPolicy

SHARED EXCLUSIVE

SHARED compatible INcompatible

EXCLUSIVE INcompatible compatible

OfferedRequested

89API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

I f m u l t i p l e DDS_DataWriter o b j e c t s w i t h t h e s a m eDDS_OwnershipStrengthQosPolicy modify the same instance, allDDS_DataReader objects will make the same choice of the particularDDS_DataWriter that is the owner. The DDS_DataReader is also notified of thisvia a s ta tus change that i s access ible by means of the Listener orDDS_Condition mechanisms.

Ownership of an InstanceDDS_DataWriter objects are not aware whether they own a particular instance.There is no error or notification given to a DDS_DataWriter that modifies aninstance it does not currently own.

TopicQosThis QosPolicy can be set on a DDS_Topic. The DDS_DataWriter and/orDDS_DataReader c an copy t h i s qos b y u s i n g t h e o p e r a t i o n sDDS_Publisher /Subscriber_copy_from_topic_qos and thenDDS_DataWriter/DataReader_set_qos. That way the application canrelatively easily ensure the QosPolicy for the DDS_Topic, DDS_DataReader andDDS_DataWriter are consistent

3.1.3.12 DDS_OwnershipStrengthQosPolicy

Synopsis#include <dds_dcps.h>

struct DDS_OwnershipStrengthQosPolicy { DDS_long value; };

DescriptionThis QosPolicy specif ies the value of the ownership s t rength of aDDS_DataWriter used to determine the ownership of an instance.

AttributesDDS_long value - specifies the ownership strength of the DDS_DataWriter.

Detailed DescriptionThis QosPolicy specif ies the value of the ownership s t rength of aDDS_DataWriter used to determine the ownership of an instance. This ownershipis used to arbitrate among multiple DDS_DataWriter objects that attempt tom o d i f y t h e s a m e i n s t a n c e . T h i s QosPolicy o n l y a p p l i e s i f t h eDDS_OwnershipQosPolicy is of kind DDS_EXCLUSIVE_OWNERSHIP_QOS. Formore information, see DDS_OwnershipQosPolicy.

90API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

This QosPolicy is applicable to a DDS_DataWriter only. After enabling of theconcerning DDS_Entity, this QosPolicy may be changed by using theDDS_DataWriter_set_qos operation. When changed, the ownership of theinstances may change with it.

3.1.3.13 DDS_PartitionQosPolicy

Synopsis#include <dds_dcps.h>struct DDS_PartitionQosPolicy { DDS_StringSeq name; };

DescriptionT h i s QosPolicy s pec i f i e s t he l og i ca l partitions i n wh i ch th eDDS_Subscribers and DDS_Publishers are active.

AttributesDDS_StringSeq name - holds the sequence of strings, which specifies the

partitions

Detailed DescriptionThis QosPolicy specifies the logical partitions inside the domain in which theDDS_Subscribers and DDS_Publishers are active. This QosPolicy isparticularly used to create a separate subspace, like a real domain versus asimulation domain. A DDS_Publisher and/or DDS_Subscriber can participatein more than one partition. Each string in the sequence of strings name defines apartition name. A partition name may contain wildcards. Sharing apartition means that at least one of the partition names in the sequencematches. When none of the partition names match, it is not considered an“incompatible” QoS and does not trigger any listeners or conditions. It onlymeans that no communication is established. The default value of the attribute is anempty (zero-sized) sequence. This is treated as a special value that matches thepartition.This QosPolicy is applicable to a DDS_Publisher and DDS_Subscriber. Afterenabling of the concerning DDS_Entity, this QosPolicy may be changed by usingthe DDS_<DDS_Entity>_set_qos operation. When changed, it modifies theassociation of DDS_DataReader and DDS_DataWriter objects. It may establishnew associations or break existing associations. By default, DDS_DataWriter andDDS_DataReader objects belonging to a DDS_Publisher or DDS_Subscriberthat do not specify a DDS_PartitionQosPolicy, will participate in the defaultpartition. In this case the partition name is “”.

91API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

Requested/OfferedThe offered setting of this QosPolicy is independent of the one requested, in otherwords they are never considered incompatible. The communication will not ber e j e c t e d o n a c c o u n t o f t h i s QosPolicy. T h e n o t i f i c a t i o nDDS_OFFERED_INCOMPATIBLE_QOS s t a tus on the offe r ing s ide orDDS_REQUESTED_INCOMPATIBLE_QOS status on the requesting side will not beraised.

3.1.3.14 DDS_PresentationQosPolicy

Synopsis#include <dds_dcps.h>

enum DDS_PresentationQosPolicyAccessScopeKind { DDS_INSTANCE_PRESENTATION_QOS, DDS_TOPIC_PRESENTATION_QOS, DDS_GROUP_PRESENTATION_QOS };struct DDS_PresentationQosPolicy { DDS_PresentationQosPolicyAccessScopeKind access_scope; DDS_boolean coherent_access; DDS_boolean ordered_access; };

DescriptionThis QosPolicy controls the extent to which changes to data-instances can bemade dependent on each other, the order in which they need to be presented to theuser and also the kind of dependencies that can be propagated and maintained by theData Distribution Service.

AttributesPresentationQosPolicyAccessScopeKind access_scope - specifies the

granularity of the changes that needs to be preserved when communicating a setof samples and the granularity of the ordering in which these changes need to bepresented to the user.

boolean coherent_access - controls whether the Data Distribution Service willpreserve the groupings of changes, as indicated by the access_scope, madeb y a p u b l i s h i n g a p p l i c a t i o n b y m e a n s o f t h e o p e r a t i o n sbegin_coherent_change and end_coherent_change.

boolean ordered_access - controls whether the Data Distribution Service willpreserve the order of the changes, as indicated by the access_scope.

92API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

Detailed DescriptionThe support for ‘coherent changes’ enables a publishing application to change thevalue of several data-instances that could belong to the same or different topics andhave those changes be seen ‘atomically’ by the readers. This is useful in cases wherethe values are inter-related. For example, if there are two data-instances representingthe ‘altitude’ and ‘velocity vector’ of the same aircraft and both are changed, it maybe useful to communicate those values in a way the reader can see both together;otherwise it may erroneously interpret that the aircraft is on a collision course.Basically this QosPolicy allows a Publisher to group a number of samples byenclosing them within calls to DDS_Publisher_begin_coherent_change andDDS_Publisher_end_coherent_change and treat them as if they are to becommunicated as a single message. That is, the receiver will only be able to accessthe data after all the modifications in the set are available at the receiver end.Samples that belong to a (yet) unfinished coherent update consume resource limitsfrom the receiving DataReader, but are not (yet) accessible through its history, andcannot (yet) push samples out of its history. In order for the DataReader to storesamples outside its history administration, its ResourceLimitsQosPolicyshould have a value for max_samples_per_instance that is bigger than thedepth value of its HistoryQosPolicy.If not enough resources are available to hold an incoming sample that belongs to anunfinished transaction, one of the following things may happen.• When some of the resources are in use by the history of the DataReader, the

incoming sample will be rejected, and the DataReader will be notified of aSAMPLE_REJECTED event. This will cause the delivery mechanism to retrydelivery of the rejected sample at a later moment in time, in the expectation thatthe application will free resources by actively taking samples out of the readerhistory.

• When all the available resources are in use by samples belonging to unfinishedcoherent updates, the application has no way to free up resources and thetransaction is either ‘deadlocked’ by itself (i.e. it is too big for the amount ofavailable resources) or by one or more other incomplete transactions. To break outof this deadlock, all samples belonging to the same transaction as the currentlyincoming sample will be dropped, and the DataReader will be notified of aSAMPLE_LOST event. No attempt will be made to retransmit the droppedtransaction. To avoid this scenario, it is important to make sure the DataReaderhas set its ResourceLimits to accommodate for the worst case history size PLUSthe worst case transaction size. In other words, if Sh represents the worst case sizeof the required history, St represents the worst case size of single transaction andNt represents the worst case number of concurrent transactions, then theResourceLimits should accommodate for Sh + (St * Nt).

93API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

A connectivity change may occur in the middle of a set of coherent changes; forexample, the set of partitions used by the Publisher or one of its Subscribers maychange, a late-joining DataReader may appear on the network, or a communicationfailure may occur. In the event that such a change prevents an entity from receivingthe entire set of coherent changes, that entity must behave as if it had received noneof the set.The support for ‘ordered_access’ enables a subscribing application to viewchanges in the order in which they occurred. Ordering is always determinedaccording to the applicable DestinationOrderQosPolicy setting. Depending onthe selected access_scope, ordering is either on a per instance basis (this is thedefault behaviour, even when ordered_access is set to FALSE), on a perDataReader basis or across all DataReaders that span the Subscriber. In case ofordered_access with an access_scope of GROUP, the Subscriber will enforcethat all its DataReaders share the same DestinationOrderQosPolicy setting.The DestinationOrderQosPolicy setting of the first DataReader created forthat Subscriber will then determine the DestinationOrderQosPolicy settingthat is allowed for all subsequent DataReaders. Conflicting settings will result in anINCONSISTENT_POLICY error.The PresentationQosPolicy is applicable to a Publisher and Subscriber.After enabling of the concerning Entity, this QosPolicy cannot be changed anymore.

AttributesThe PresentationQosPolicy is applicable to both Publisher andSubscriber, but behaves differently on the publishing side and the subscribingside. The setting of coherent_access on a DDS_Publisher controls whetherthat Publisher will preserve the coherency of changes (enclosed by calls toDDS_Publisher_begin_coherent_change and end_coherent_change), asindicated by its access_scope and as made available by its embeddedDataWriters. However, the Subscriber settings determine whether a coherent set ofsamples will actually be delivered to the subscribing application in a coherent way.• If a Publisher or Subscriber sets coherent_access to FALSE, it indicates that it

does not want to maintain coherency between the different samples in a set: aSubscriber that receives only a part of this set may still deliver this partial set ofsamples to its embedded DataReaders.

• If both Publisher and Subscriber set coherent_access to TRUE, they indicatethat they want to maintain coherency between the different samples in a set: aSubscriber that receives only a part of this set may not deliver this partial set ofsamples to its embedded DataReaders; it needs to wait for the set to becomecomplete, and it will flush this partial set when it concludes that it will never beable to complete it.

94API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

Coherency is implemented on top of a transaction mechanism between individualDataWriters and DataReaders; completeness of a coherent set is determined by thesuccessful completion of each of its participating transactions. The value of theaccess_scope attribute determines which combination of transactionsconstitute the contents of a coherent set.

The setting of ordered_access has no impact on the way in which a Publishertransmits its samples (although it does influence the RxO properties of thisPublisher), but basically it determines whether a Subscriber will preserve theordering of samples when the subscribing application uses its embeddedDataReaders to read or take samples:• If a Subscriber sets ordered_access to FALSE, it indicates that it does not want

to maintain ordering between the different samples it receives: a subscribingapplication that reads or takes samples will receive these samples ordered by theirkey-values, which does probably not resemble the order they were written in.

• If a Subscriber sets ordered_access to TRUE, it indicates that it does want tomaintain ordering within the specified access_scope between the differentsamples it receives: a subscribing application that reads or takes samples willreceives these samples sorted by the order in which they were written.

The access_scope determines the maximum extent of coherent and/or orderedchanges:• If access_scope is set to DDS_INSTANCE_PRESENTATION_QOS andcoherent_access is set to TRUE, then the Subscriber will behave, with respectto maintaining coherency, in a way similar to an access_scope that is set toDDS_TOPIC_PRESENTATION_QOS. This is caused by the fact that coherency isdefined as the successful completion of all participating transactions. If aDataWriter writes a transaction containing samples from different instances, and aconnected DataReader misses one of these samples, then the transaction failedand the coherent set is considered incomplete by the receiving DataReader. Itdoesn’t matter that all the other instances have received their samplessuccessfully; an unsuccessful transaction by definition results in an incompletecoherent set. In that respect the DDS can offer no granularity that is morefine-grained with respect to coherency than that described by theDDS_TOPIC_PRESENTATION_QOS.If access_scope is set to DDS_INSTANCE_PRESENTATION_QOS andordered_access is set to TRUE, then the subscriber will maintain orderingbetween samples belonging to the same instance. Samples belonging to differentinstances will still be grouped by their key-values instead of by the order in whichthey were received.

95API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

• If access_scope is set to DDS_TOPIC_PRESENTATION_QOS andcoherent_access is set to TRUE, then the DDS will define the scope of acoherent set on individual transactions. So a coherent set that spans samplescoming from multiple DataWriters (indicated by its enclosure within calls toDDS_Publisher_begin_coherent_change andDDS_Publisher_end_coherent_change on their shared Publisher), ischopped up into separate and disjunct transactions (one for each participatingDataWriter), where each transaction is processed separately. On the subscribingside this may result in the successful completion of some of these transactions,and the unsuccessful completion of some others. In such cases all DataReadersthat received successful transactions will deliver the embedded content to theirapplications, without waiting for the completion of other transactions in otherDataReaders connected to the same Subscriber.If access_scope is set to DDS_TOPIC_PRESENTATION_QOS andordered_access is set to TRUE, then the subscriber will maintain orderingbetween samples belonging to the same DataReader. This means that samplesbelonging to the same instance in the same DataReader may no longer be receivedconsecutively if samples belonging to different instances were written in between.It is possible to read/take a limited batch of ordered samples (wheremax_samples != LENGTH_UNLIMITED). In that case the DataReader will keepa bookmark, so that in subsequent read/take operations your application can startwhere the previous read/take call left off. There are two ways for the middlewareto indicate that you completed a full iteration: - The amount of samples returned is smaller than the amount of samples

requested. In that case the bookmark is automatically reset and the nextread/take will begin a new iteration right from the start of the ordered list.

- Your read/take call returns RETCODE_NO_DATA, indicating that there are nomore samples matching your criteria after the current bookmark. In that case thebookmark is reset as well.

The bookmark is also reset in the following cases: - A read/take call uses different masks than the previous invocation of read/take. - A read/take call uses a different query than the previous invocation of read/take.

• If access_scope is set to DDS_GROUP_PRESENTATION_QOS andcoherent_access is set to TRUE, then the DDS will define the scope of acoherent set on the sum of all participating transactions. So a coherent set thatspans samples coming from multiple DataWriters (indicated by its enclosurewithin calls to DDS_Publisher_begin_coherent_change andDDS_Publisher_end_coherent_change on their shared Publisher), ischopped up into separate and disjunct transactions (one for each participatingDataWriter), where each transactions is processed separately. On the subscribing

96API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

side this may result in the successful completion of some of these transactions,and the unsuccessful completion of some others. However, each DataReader isonly allowed to deliver the embedded content when all participating transactionscompleted successfully. This means that DataReaders that received successfultransactions will need to wait for all other DataReaders attached to the sameSubscriber to also complete their transactions successfully. If one or moreDataReaders conclude that they will not be able to complete their transactionssuccessfully, then all DataReaders that participate in the original coherent set willflush the content of their transactions. In order for the application to access thestate of all DataReaders that span the coherent update, a separate read/takeoperation will need to be performed on each of the concerned DataReaders. Tokeep the history state of the DataReaders consistent in between the successiveinvocations of the read/take operations on the various readers, the DataReadersshould be locked for incoming updates by invoking theDDS_Subscriber_begin_access on the Subscriber prior to accessing the firstDataReader. If all concerned DataReaders have been accessed properly, they canbe unlocked for incoming updates by invoking theDDS_Subscriber_end_access on the Subscriber. Note that in this case aSubscriber is created in a disabled state. This allows the application to create allconcerned DataReaders, preventing any transactions from completingprematurely before all DataReaders have been created. The application mustexplicitly enable the subscriber after it has finished creating DataReaders. SeeSection 3.5.1.6, DDS_Subscriber_enable (inherited), for additional information. If access_scope is set to DDS_GROUP_PRESENTATION_QOS andordered_access is set to TRUE, then ordering is maintained between samplesthat are written by DataWriters attached to a common Publisher and received byDataReaders attached to a common Subscriber. This way the subscribingapplication can access the changes as a unit and/or in the proper order. However,this does not necessarily imply that the subscribing application will indeed accessthe changes as a unit and/or in the correct order. For that to occur, the subscribingapplication must use the proper logic in accessing its datareaders: - Upon notification by the callback operation on_data_on_readers of the

SubscriberListener or when triggered by the similar DDS_DATA_ON_READERSstatus of the Subscriber’s DDS_StatusCondition, the application usesDDS_Subscriber_begin_access on the Subscriber to indicate it will beaccessing data through the Subscriber. This will lock the embedded datareadersfor any incoming messages during the coherent data access.

97API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

- Then it calls DDS_Subscriber_get_datareaders on the Subscriber to getthe list of DataReader objects where data samples are available. Note that whenordered_access is TRUE, then the list of DataReaders may contain the samereader several times. In this manner the correct sample order can be maintainedamong samples in different DataReader objects.

- Following this it calls DDS_DataReader_read or DDS_DataReader_takeon each DataReader in the same order returned to access all the relevantchanges in the DataReader. Note that when ordered_access is TRUE, youshould only read or take one sample at a time.

- Once it has called read or take on all the readers, it callsDDS_Subscriber_end_access on the Subscriber. This will unlock theembedded datareaders again.

Requested/OfferedIn case the Requested/Offered QosPolicy are incompatible, the notificationDDS_OFFERED_INCOMPATIBLE_QOS s ta tus on the offer ing s ide andDDS_REQUESTED_INCOMPATIBLE_QOS status on the requesting side is raised.

The value offered is considered compatible with the value requested if and only ifthe following conditions are met:1. The inequality “offered access_scope >= requested access_scope”

evaluates to ‘TRUE’. For the purposes of this inequality, the values ofPRESENTATION access_scope are considered ordered such that INSTANCE< TOPIC < GROUP.

2. Requested coherent_access is FALSE, or else both offered and requestedcoherent_access are TRUE.

3. Requested ordered_access is FALSE, or else both offered and requestedordered_access are TRUE.

In case the quality offered by the Publisher is better than the value requested by theSubscriber, the subscriber’s values determine the resulting behaviour for thesubscribing application. In other words, the quality specified at the Subscriber siteoverrules the corresponding value at the Publisher site.

Table 13: Requested/Offered PresentationQosPolicy

INSTANCE Topic Group

instance compatible INcompatible INcompatibletopic compatible compatible INcompatiblegroup compatible compatible compatible

OfferedRequested

98API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

Consider the following scenario:1. A Publisher publishes coherent sets with access_scope is GROUP and

coherent_access is TRUE.2. A Subscriber subscribes to these coherent sets with access_scope is TOPIC

and coherent_access is TRUE.3. The Publisher writes a coherent set consisting of 2 samples of Topic A, and 2

samples of Topic B.4. During transmission, the first sample of Topic B gets lost.According to the access_scope of the Publisher, the coherent set is incompleteand can therefore not be delivered. However, according to the access_scope ofthe Subscriber, coherency needs to be maintained on a per Reader/Writer pair basisso the samples for Topic A will be delivered upon arrival, but the samples for TopicB will not.Basically, when both coherent_access and ordered_access are set to FALSE,then the access_scope serves no other purpose than to determine connectivitybetween Publishers and Subscribers.

3.1.3.15 DDS_ReaderDataLifecycleQosPolicy

Synopsis#include <dds_dcps.h> enum DDS_InvalidSampleVisibilityQosPolicyKind { DDS_NO_INVALID_SAMPLES, DDS_MINIMUM_INVALID_SAMPLES, DDS_ALL_INVALID_SAMPLES }; struct DDS_InvalidSampleVisibilityQosPolicy { DDS_InvalidSampleVisibilityQosPolicyKind kind; }; struct DDS_ReaderDataLifecycleQosPolicy { DDS_Duration_t autopurge_nowriter_samples_delay; DDS_Duration_t autopurge_disposed_samples_delay; DDS_boolean autopurge_dispose_all; DDS_boolean enable_invalid_samples; DDS_InvalidSampleVisibilityQosPolicy invalid_sample_visibility; };

DescriptionThis QosPolicy specifies the maximum duration for which the DDS_DataReaderwill maintain information regarding a data instance for which the instance_statebecomes either DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE orDDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE. The policy also controlswhether state changes will potentially be communicated using so-called ‘invalid’samples.

99API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

AttributesDDS_Duration_t autopurge_nowriter_samples_delay - specifies the

duration for which the DDS_DataReader will maintain information regarding ada t a i n s t ance fo r wh ich t he instance_state b e com esDDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE. By default the durationvalue is DDS_DURATION_INFINITE. When the delay time has expired, the datainstance is marked so that it can be purged in the next garbage collection sweep.

DDS_Duration_t autopurge_disposed_samples_delay - specifies theduration for which the DDS_DataReader will maintain information regarding ada t a i n s t a nce fo r wh ich t he instance_state b e com esDDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE. By default the durationvalue is DDS_DURATION_INFINITE. When the delay time has expired, the datainstance is marked so that it can be purged in the next garbage collection sweep.

DDS_Boolean autopurge_dispose_all - Determines whether all samples inthe DDS_DataReader w i l l b e p u rg e d a u t o m a t i c a l l y w h e n adispose_all_data() call is performed on the DDS_Topic that is associatedwith the DDS_DataReader. If this attribute set to TRUE, no more samples willexist in the DDS_DataReader after the dispose_all_data has beenprocessed. Because all samples are purged, no data available events will benot i f ied to potent ia l Lis teners or Condi t ions that are se t for theDDS_DataReader. If this attribute is set to FALSE, the dispose_all_data()behaves as if each individual instance was disposed separately.

DDS_boolean enable_invalid_samples - Insert dummy samples if no datasample is available to notify readers of an instance_state change. Bydefault the value is true.

NOTE: This feature is deprecated. I t i s recommended that you useinvalid_sample_visibility instead.

DDS_InvalidSampleVisibilityQosPolicyinvalid_sample_visibility - Insert dummy samples if no data sample isavailable, to notify readers of an instance_state change. By default thevalue is DDS_MINIMUM_INVALID_SAMPLES.

Detailed DescriptionThis QosPolicy specifies the maximum duration for which the DDS_DataReaderwill maintain information regarding a data instance for which the instance_statebecomes either DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE orDDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE. The DDS_DataReadermanages resources for instances and samples of those instances. The amount ofr e s o u r c e s m a nag e d d e pe nd s o n o t h e r QosPolicies l i k e t h eDDS_HistoryQosPolicy and the DDS_ResourceLimitsQosPolicy. The

100API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

DDS_DataReader can only release resources for data instances for which alls a m p l e s h a v e b e e n t a k e n a n d t h e instance_state h a s b e c o m eDDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE or DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE. If an application does not take the samplesbe long ing to a da t a i n s t ance w i th such an instance_state , t heDDS_DataReader will never be able to release the maintained resources. By meansof this QosPolicy the application can instruct the DDS_DataReader to release allresources related to the relevant data instance after a specified duration.There is one exception to this rule. If the autopurge_dispose_all attribute isTRUE, the maintained resources in the DDS_DataReader are cleaned upimmediately in case dispose_all_data() is called on the DDS_Topic that isassociated with the DDS_DataReader.Instance state changes are communicated to a DDS_DataReader by means of theSampleInfo accompanying a data sample. If no samples are available in theDDS_DataReader, a so-called ‘invalid sample’ can be injected with the sole purposeof notifying applications of the instance state. This behaviour is configured by theDDS_InvalidSampleVisibilityQosPolicy.• If invalid_sample_visibility is set to DDS_NO_INVALID_SAMPLES,

applications will be notified of instance_state changes only if there is asample available in the DDS_DataReader. The SampleInfo belonging to thissample will contain the updated instance state.

• If invalid_sample_visibility is set toDDS_MINIMUM_INVALID_SAMPLES, the middleware will try to update theinstance_state on available samples in the DataReader. If no sample isavailable, an invalid sample will be injected. These samples contain only the keyvalues of the instance. The SampleInfo for invalid samples will have the‘valid_data’ flag disabled, and contain the updated instance state.

• If invalid_sample_visibility is set to DDS_ALL_INVALID_SAMPLES,every change in the instance_state will be communicated by a separateinvalid sample.

NOTE: This value (DDS_ALL_INVALID_SAMPLES) is not yet implemented.It is scheduled for a future release.

An alternative but deprecated way to determine the visibility of state changes is toset a boolean value for the enable_invalid_samples field.• When TRUE, the behavior is similar to the DDS_MINIMUM_INVALID_SAMPLES

value of the DDS_InvalidSampleVisibilityQosPolicy field.• When FALSE, the behavior is similar to the DDS_NO_INVALID_SAMPLES value

of the DDS_InvalidSampleVisibilityQosPolicy field.

101API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

You cannot set both the the enable_invalid_samples field AND theinvalid_sample_visibility field. If both deviate from their factory default,this is considered a DDS_RETCODE_INCONSISTENT_POLICY. If only one of thefields deviates from its factory default, then that setting will be leading. However,modifying the default value of the enable_invalid_samples field willautomatically result in a warning message stating that you are using deprecatedfunctionality.This QosPolicy is applicable to a DDS_DataReader only. After the relevantDDS_DataReader is enabled, this QosPolicy can be changed using the set_qosoperation.

3.1.3.16 DDS_ReliabilityQosPolicy

Synopsis#include <dds_dcps.h>

enum DDS_ReliabilityQosPolicyKind { DDS_BEST_EFFORT_RELIABILITY_QOS, DDS_RELIABLE_RELIABILITY_QOS };struct DDS_ReliabilityQosPolicy { DDS_ReliabilityQosPolicyKind kind; DDS_Duration_t max_blocking_time; DDS_boolean synchronous; };

DescriptionThis QosPolicy controls the level of reliability of the data distribution offered orrequested by the DDS_DataWriters and DDS_DataReaders.

AttributesDDS_ReliabilityQosPolicyKind kind - specifies the type of reliability which

may be DDS_BEST_EFFORT_RELIABILITY_QOS orDDS_RELIABLE_RELIABILITY_QOS.

DDS_Duration_t max_blocking_time - specifies the maximum time theDDS_DataWriter_write operation may block when the DDS_DataWriterdoes not have space to store the value written or when synchronouscommunication is specified and all expected acknowledgements are not yetreceived.

DDS_boolean synchronous - specifies whether a DataWriter should wait foracknowledgements by all connected DataReaders that also have set asynchronous ReliabilityQosPolicy.

102API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

I t i s a d v i s a b le o n l y t o u s e t h i s p o l i c y in c o m b i n a t i o n w i t hRELIABLE_RELIABILITY; if used in combination with BEST_EFFORT datamay not arrive at the DataReader, resulting in a timeout at the DataWriterindicating that the data has not been received.Acknowledgments are always sent RELIABLE so that when the DataWriterencounters a timeout it is guaranteed that the DataReader hasn’t received thedata.NOTE: This is an OpenSplice-specific parameter, it is not part of the DDSSpecification.

Detailed DescriptionThis QosPolicy controls the level of reliability of the data distribution requestedby a DDS_DataReader or offered by a DDS_DataWriter. In other words, itcontrols whether data is allowed to get lost in transmission or not.This QosPolicy is applicable to a DDS_DataReader, DDS_DataWriter andDDS_Topic. After enabling of the concerning DDS_Entity, this QosPolicycannot be changed any more.

AttributesThe QosPolicy is controlled by the attribute kind which can be:• DDS_RELIABLE_RELIABILITY_QOS - the Data Distribution Service will attempt

to deliver all samples in the DDS_DataWriters history; arrival-checks areperformed and data may get re-transmitted in case of lost data. In the steady-state(no modifications communicated via the DDS_DataWriter) the DataDistribution Service guarantees that all samples in the DDS_DataWriter historywill eventually be delivered to the all DDS_DataReader objects. Outside thesteady-state the DDS_HistoryQosPolicy andDDS_ResourceLimitsQosPolicy determine how samples become part of thehistory and whether samples can be discarded from it. In this case also themax_blocking_time must be set

• DDS_BEST_EFFORT_RELIABILITY_QOS - the Data Distribution Service willonly attempt to deliver the data; no arrival-checks are being performed and anylost data is not re-transmitted (non-reliable). Presumably new values for thesamples are generated often enough by the application so that it is not necessary toresent or acknowledge any samples.

The effect of the attribute max_blocking_time depends on the setting of theDDS_HistoryQosPolicy and DDS_ResourcesLimitsQosPolicy and thesynchronous setting of the DDS_ReliabilityQosPolicy. In case theDDS_HistoryQosPolicy kind is set to DDS_KEEP_ALL_HISTORY_QOS, theDDS_DataWriter_write operation on the DDS_DataWriter may block if the

103API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

m o d i f i c a t i o n w o u l d c a u s e o n e o f t h e l i m i t s s p e c i f i e d i n t h eDDS_ResourceLimitsQosPolicy to be exceeded. Also in case the synchronousattribute value of the ReliabilityQosPolicy is set to TRUE on both sides of apair of connected DataWriters and DataReaders, then the DataWriter willwait until all its connected synchronous DataReaders have acknowledged thedata. Under these circumstances, the max_blocking_time attribute of theDDS_ReliabilityQosPolicy configures the maximum duration theDDS_DataWriter_write operation may block.

Requested/OfferedIn case the Requested/Offered QosPolicy are incompatible, the notificationDDS_OFFERED_INCOMPATIBLE_QOS s ta tus on the offer ing s ide andDDS_REQUESTED_INCOMPATIBLE_QOS status on the requesting side is raised.

DDS_TopicQosThis QosPolicy can be set on a DDS_Topic. The DDS_DataWriter and/orDDS_DataReader c a n c op y t h i s qo s b y u s i ng t he op e r a t i on sDDS_<DDS_Entity>_copy_from_topic_qos and t he nDDS_<DDS_Entity>_set_qos. That way the application can relatively easilyensure the QosPolicy fo r the DDS_Topic , DDS_DataReader andDDS_DataWriter are consistent.

3.1.3.17 DDS_ResourceLimitsQosPolicy

Synopsis#include <dds_dcps.h>

struct DDS_ResourceLimitsQosPolicy { DDS_long max_samples; DDS_long max_instances; DDS_long max_samples_per_instance; };

DescriptionThis QosPolicy will specify the maximum amount of resources, which can be usedby a DDS_DataWriter or DDS_DataReader.

Table 14: Requested/Offered DDS_ReliabilityQosPolicy

BEST_EFFORT RELIABLE

BEST_EFFORT compatible INcompatible

RELIABLE compatible compatible

OfferedRequested

104API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

AttributesDDS_long max_samples - specifies the maximum number of data samples for all

instances for any single DDS_DataWriter (or DDS_DataReader). By default,DDS_LENGTH_UNLIMITED.

DDS_long max_instances - specifies the maximum number of instances for anys i n g l e DDS_DataWriter ( o r DDS_DataReader ) . B y d e f a u l t ,DDS_LENGTH_UNLIMITED.

DDS_long max_samples_per_instance - specifies the maximum number ofsamples of any single instance for any single DDS_DataWriter (orDDS_DataReader). By default, DDS_LENGTH_UNLIMITED.

Detailed DescriptionThis QosPolicy controls the maximum amount of resources that the DataDistribution Service can use in order to meet the requirements imposed by theapplication and other QosPolicy settings.This QosPolicy is applicable to a DDS_DataReader, a DDS_DataWriter and aDDS_Topic. After enabling of the concerning DDS_Entity, this QosPolicycannot be changed any more.

Requested/OfferedThe value of the QosPolicy offered is independent of the one requested, in otherwords they are never considered incompatible. The communication will not ber e j e c t e d o n a c c o u n t o f t h i s QosPolicy. T h e n o t i f i c a t i o nDDS_OFFERED_INCOMPATIBLE_QOS s t a tus on the offe r ing s ide orDDS_REQUESTED_INCOMPATIBLE_QOS status on the requesting side will not beraised.

Resource limitsIf the DDS_DataWriter objects are publishing samples faster than they are takenby the DDS_DataReader objects, the Data Distribution Service will eventually hitagainst some of the QosPolicy-imposed resource limits. Note that this may occurwhen just a single DDS_DataReader cannot keep up with its correspondingDDS_DataWriter.In case the DDS_HistoryQosPolicy is DDS_KEEP_LAST_HISTORY_QOS, thesetting of DDS_ResourceLimitsQosPolicy max_samples_per_instancemust be compatible with the DDS_HistoryQosPolicy depth. For these twoQosPolicy settings to be compatible, they must verify that depth <=max_samples_per_instance.

105API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

DDS_TopicQosThis QosPolicy can be set on a DDS_Topic. The DDS_DataWriter and/orDDS_DataReader c a n c op y t h i s qo s b y u s i ng t he op e r a t i on sDDS_<DDS_Entity>_copy_from_topic_qos and t he nDDS_<DDS_Entity>_set_qos. That way the application can relatively easilyensure the QosPolicy fo r the DDS_Topic , DDS_DataReader andDDS_DataWriter are consistent.

3.1.3.18 DDS_SchedulingQosPolicyNOTE: This is an OpenSplice-specific QosPolicy, it is not part of the DDSSpecification.

ScopeDDS

Synopsis#include <dds_dcps.h>

enum DDS_SchedulingClassQosPolicyKind { DDS_SCHEDULE_DEFAULT, DDS_SCHEDULE_TIMESHARING, DDS_SCHEDULE_REALTIME };struct DDS_SchedulingClassQosPolicy { DDS_SchedulingClassQosPolicyKind kind; };enum DDS_SchedulingPriorityQosPolicyKind { DDS_PRIORITY_RELATIVE, DDS_PRIORITY_ABSOLUTE };struct DDS_SchedulingPriorityQosPolicy { DDS_SchedulingPriorityQosPolicyKind kind; };struct DDS_SchedulingQosPolicy { DDS_SchedulingClassQosPolicy scheduling_class; DDS_SchedulingPriorityQosPolicy scheduling_priority_kind; DDS_long scheduling_priority; };

DescriptionThis QosPolicy specifies the scheduling parameters that will be used for a threadthat is spawned by the DDS_DomainParticipant.Note that some scheduling parameters may not be supported by the underlyingOperating System or that you may need special privileges to select particularsettings.

106API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

AttributesDDS_SchedulingClassQosPolicyKind scheduling_class.kind - specifies

the scheduling class used by the Operating System, which may beDDS_SCHEDULE_DEFAULT, DDS_SCHEDULE_TIMESHARING o rDDS_SCHEDULE_REALTIME. Threads can only be spawned within thescheduling classes that are supported by the underlying Operating System.

DDS_SchedulingPriorityQosPolicyKind scheduling_priority_kind.kind -specifies the priority type, which may be either DDS_PRIORITY_RELATIVE orDDS_PRIORITY_ABSOLUTE.

DDS_long scheduling_priority - specifies the priority that will be assigned tothreads spawned by the DDS_DomainParticipant. Threads can only bespawned with priorities that are supported by the underlying Operating System.

Detailed DescriptionThis QosPolicy specifies the scheduling parameters that will be used for threadsspawned by the DDS_DomainParticipant. Note that some scheduling parametersmay not be supported by the underlying Operating System or that you may needspecial privileges to select particular settings. Refer to the documentation of yourOS for more details on this subject.Although the behaviour of the scheduling_class is highly dependent on theunderlying OS, in general when running in a Timesharing class your thread willneed to regularly yield execution to other threads of equal priority. In a Realtimeclass, your thread normally runs until completion and can only be pre-empted byhigher priority threads. Often, the highest range of priorities is not accessiblethrough a Timesharing Class.The scheduling_priority_kind determines whether the specifiedscheduling_priority should be interpreted as an absolute priority or whether itshould be interpreted relative to the priority of its creator, in this case the priority ofthe thread that created the DDS_DomainParticipant.

3.1.3.19 DDS_TimeBasedFilterQosPolicy

Synopsis#include <dds_dcps.h>

struct DDS_TimeBasedFilterQosPolicy { DDS_Duration_t minimum_separation; };

DescriptionThis QosPolicy specifies a period after receiving a sample for a particular instanceduring which a DataReader will filter out new samples for the same instance.

107API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

At the end of the period the latest state of the instance will be notified and a newfilter period will start. If there are no new samples in a period the filter will notnotify the same latest already-notified state and it will wait for a new sample on thisparticular instance to start a new period.In the case where the reliability QoS kind is RELIABLE the system guarantees thatthe latest state is notified.Effectively the DataReader will receive at most one sample with the latest stateper period for each instance.

AttributesDDS_Duration_t minimum_separation - specifies the minimum period

between received samples to be passed through the filter. The default value is 0,meaning that all samples are accepted.

Detailed DescriptionThis QosPolicy allows a DataReader to indicate that it is not interested inprocessing all samples for each instance. Instead it requests at most one change perminimum_separation period.The filter is applied to each data-instance separately. This means that new instanceswill not be filtered, no matter what the minimum_separation period or theirpublication time is. The filter is only applied to samples belonging to the sameinstance, limiting the rate at which the DataReader is notified of the most currentvalue of each instance. This can be helpful in situations where some nodes arecapable of generating data much faster than others can consume it. Instance statechanges are not affected by the filter, so a DataReader always contains the lateststate of an instance.The minimum_separation period must be consistent with the DeadlineQos. Ifthe minimum_separation period is greater than the deadline period, the deadlinecannot be met; therefore the two QoS policies are inconsistent. An attempt to setthese policies with inconsistent values will result in a failure to create theDataReader or an INCONSISTENT_POLICY return value.This QosPolicy is applicable to a DDS_DataReader only. After enabling therelevant DDS_DataReader, this QosPolicy can be changed using the set_qosoperation.

3.1.3.20 DDS_TopicDataQosPolicy

Synopsis#include <dds_dcps.h>

struct DDS_TopicDataQosPolicy { DDS_sequence_octet value; };

108API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

DescriptionThis QosPolicy allows the application to attach additional information to aDDS_Topic DDS_Entity. This informat ion is d is t r ibuted wi th theDDS_BuiltinTopics.

AttributesDDS_sequence_octet value – a sequence of octets that holds the application

topic data. By default, the sequence has length 0.

Detailed DescriptionThis QosPolicy allows the application to attach additional information to aDDS_Topic Entity. This information is distributed with the BuiltinTopic. Anapplication that discovers a new DDS_Topic entity, can use this information to addadditional functionality. The DDS_TopicDataQosPolicy is changeable andupdates of the BuiltinTopic instance must be expected. Note that the DataDistribution Service is not aware of the real structure of the topic data (the DataDistribution System handles it as an opaque type) and that the application isresponsible for correct mapping on structural types for the specific platform.

3.1.3.21 DDS_TransportPriorityQosPolicy

Synopsis#include <dds_dcps.h>

struct DDS_TransportPriorityQosPolicy { DDS_long value; };

DescriptionThis QosPolicy specifies the priority with which the Data Distribution System canhandle the data produced by the DDS_DataWriter.

AttributesDDS_long value – specifies the priority with which the Data Distribution System

can handle the data produced by the DDS_DataWriter.

Detailed DescriptionThis QosPolicy specifies the priority with which the Data Distribution System canhandle the data produced by a DDS_DataWriter. This QosPolicy is considered tobe a hint to the Data Distribution Service to control the priorities of the underlyingtransport means. A higher value represents a higher priority and the full range of thetype is supported. By default the transport priority is set to 0.

109API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

The DDS_TransportPriorityQosPolicy is applicable to both DDS_Topic andDDS_DataWriter entities. After enabling of the concerning DDS_Entities, thisQosPolicy may be changed by using the set_qos operation.

TopicQosNote that changing this QosPolicy for the DDS_Topic does not influence thebehaviour of the Data Distribution System for existing DDS_DataWriter entitiesbecause this QosPolicy is only used by the operation copy_from_topic_qosand when specifying DDS_DATAWRITER_QOS_USE_TOPIC_QOS when creating theDataWriter.

3.1.3.22 DDS_UserDataQosPolicy

Synopsis#include <dds_dcps.h>

struct DDS_UserDataQosPolicy { DDS_sequence_octet value; };

DescriptionThis QosPolicy allows the application to attach additional information to aDDS_DomainParticipant , DDS_DataReader or DDS_DataWriterDDS_Entity. This information is distributed with the Builtin Topics.

AttributesDDS_sequence_octet value – is a sequence of octets that holds the application

user data. By default, the sequence has length 0.

Detailed DescriptionThis QosPolicy allows the application to attach additional information to aDDS_DomainParticipant, DDS_DataReader or DDS_DataWriter entity. Thisinformation is distributed with the Builtin Topics. An application that discovers anew DDS_Entity of the listed kind, can use this information to add additionalfunctionality. The DDS_UserDataQosPolicy is changeable and updates of theBuiltin Topic instance must be expected. Note that the Data Distribution Service isnot aware of the real structure of the user data (the Data Distribution System handlesit as an opaque type) and that the application is responsible for correct mapping onstructural types for the specific platform.

3.1.3.23 DDS_WriterDataLifecycleQosPolicy

Synopsis#include <dds_dcps.h>

struct DDS_WriterDataLifecycleQosPolicy

110API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

{ DDS_boolean autodispose_unregistered_instances; DDS_Duration_t autopurge_suspended_samples_delay; DDS_Duration_t autounregister_instance_delay; };

DescriptionThis QosPolicy drives the behaviour of a DataWriter concerning the life-cycle ofthe instances and samples that have been written by it.

AttributesDDS_boolean autodispose_unregistered_instances - specifies whether

the Data Distribution Service should automatically dispose instances that areunregistered by this DDS_DataWriter. By default this value is TRUE.

DDS_Duration_t autopurge_suspended_samples_delay – specifies theduration after which the DDS_DataWriter will automatically remove a samplefrom its history during periods in which its Publisher is suspended. Thisduration is calculated based on the source timestamp of the written sample. Bydefault the duration value is set to DDS_DURATION_INFINITE and therefore noa u to m a t i c p u rg i n g o f s a m p l e s oc c u r s . S e e S e c t i on 3 . 4 .1 .1 9 ,DDS_Publisher_suspend_publications, on page 314 for more information aboutsuspended publication.

DDS_Duration_t autounregister_instance_delay – specifies the durationafter which the DDS_DataWriter will automatically unregister an instanceafter the application wrote a sample for it and no further action is performed onthe same instance by this DDS_DataWriter afterwards. This means that whenthe application writes a new sample for this instance, the duration is recalculatedf r o m t h a t a c t i o n o n w a r d s . B y d e f a u l t t h e d u r a t i o n v a l u e i sDDS_DURATION_INFINITE and therefore no automatic unregistration occurs.

Detailed DescriptionThis QosPolicy controls the behaviour of the DDS_DataWriter with regard tothe lifecycle of the data-instances it manages, that is, the data-instances that havebeen registered either explicitly using one of the register operations or implicitlyby directly writing the data using the special DDS_HANDLE_NIL parameter. (Seealso Section 3.4.2.50, SPACE_FooDataWriter_register_instance, on page 361).The autodispose_unregistered_instances flag controls what happenswhen an instance gets unregistered by the DDS_DataWriter:• If the DDS_DataWriter unregisters the instance explicitly using eitherSPACE_FooDataWriter_unregister_instance orSPACE_FooDataWriter_unregister_instance_w_timestamp, then theautodispose_unregistered_instances flag is currently ignored and theinstance is never disposed automatically.

111API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

• If the DDS_DataWriter unregisters its instances implicitly because it is deleted,or if a DDS_DataReader detects a loss of liveliness of a connectedDDS_DataWriter, or if autounregister_instance_delay expires, then theauto_dispose_unregistered_instances flag determines whether theconcerned instances are automatically disposed (TRUE) or not (FALSE).

For DDS_DataWriters associated with TRANSIENT and PERSISTENT topicssetting the autodispose_unregister_instances attribute to TRUE wouldmean that all instances that are not explicitly unregistered by the application will bydefault be removed from the Transient and Persistent stores when the DataWriter isde l e t e d , when a l o s s o f l i ve l i n e s s i s d e t e c t e d , o r w he n t h eautounregister_instance_delay expires.

3.1.3.24 DDS_SubscriptionKeyQosPolicy

Synopsis#include <dds_dcps.h> struct DDS_SubscriptionKeyQosPolicy { DDS_boolean use_key_list, DDS_StringSeq key_list };

DescriptionThis QosPolicy allows the DataReader to define its own set of keys on the data,potentially different from the keys defined on the topic.NOTE: This is an OpenSplice-specific QosPolicy, it is not part of the DDSSpecification.

AttributesDDS_boolean use_key_list – Controls whether the alternative key list is

applied on the DataReader.DDS_StringSeq key_list – A sequence of strings with one or more names of

topic fields acting as alternative keys.

Detailed DescriptionBy using the SubscriptionKeyQosPolicy, a DataReader can force its own key-listdefinition on data samples. The consequences are that the DataReader willinternally keep track of instances based on its own key list, instead of the key listdictated by the Topic.Opera t ions tha t ope ra te on ins tances o r in s t ance hand les , such aslookup_instance or get_key_value, respect the alternative key-list and workas expected. However, since the mapping of writer instances to reader instances isno longer trivial (one writer instance may now map to more than one matching

112API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

reader instance and vice versa), a writer instance will no longer be able to fullydetermine the lifecycle of its matching reader instance, nor the value itsview_state and instance_state.In fact, by diverting from the conceptual 1 – 1 mapping between writer instance andreader instance, the writer can no longer keep an (empty) reader instance ALIVE byjust refusing to unregister its matching writer instance. That means that when areader takes all samples from a particular reader instance, that reader instance willimmediately be removed from the reader’s administration. Any subsequentreception of a message with the same keys will re-introduce the instance into thereader administration, setting its view_state back to NEW. Compare this to thedefault behaviour, where the reader instance will be kept alive as long as the writerdoes not unregister it. That causes the view_state in the reader instance to remainNOT_NEW, even if the reader has consumed all of its samples prior to receiving anupdate.Another consequence of allowing an alternative keylist is that events that arecommunicated by invalid samples (i.e. samples that have only initialized theirkeyfields) may no longer be interpreted by the reader to avoid situations in whichuninitialized non-keyfields are treated as keys in the alternative keylist. Thiseffectively means that all invalid samples (e.g. unregister messages and bothimplicit and explicit dispose messages) will be skipped and can no longer affect theinstance_state, which will therefore remain ALIVE. The only exceptions to thisare the messages that are transmitted explicitly using the writedispose() call(see Section 3.4.2.29, DDS_DataWriter_writedispose (abstract), on page 344),which always includes a full and valid sample and can therefore modify theinstance_state to NOT_ALIVE_DISPOSED.By default, the SubscriptionKeyQosPolicy is not used because use_key_list isset to FALSE.This QosPolicy is applicable to a DataReader only, and cannot be changed after theDataReader is enabled.

3.1.3.25 DDS_ReaderLifespanQosPolicy

Synopsis#include <dds_dcps.h> struct DDS_ReaderLifespanQosPolicy { DDS_boolean use_lifespan, DDS_Duration_t duration };

DescriptionAutomatically remove samples from the DataReader after a specified timeout.

113API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

NOTE: This is an OpenSplice-specific QosPolicy, it is not part of the DDSSpecification.

AttributesDDS_boolean use_lifespan – Controls whether the lifespan is applied to the

samples in the DataReader.DDS_Duration_t duration – The duration after which data loses validity and is

removed.

Detailed DescriptionThis QosPolicy is similar to the LifespanQosPolicy (applicable to Topic andDataWriter), but limited to the DataReader on which the QosPolicy is applied. Thedata is automatically removed from the DataReader if it has not been taken yet afterthe lifespan duration expires. The duration of the ReaderLifespan is added to theinsertion time of the data in the DataReader to determine the expiry time.W h e n b o t h t h e ReaderLifespanQosPolicy a n d a D a t a Wr i t e r ’sLifespanQosPolicy are applied to the same data, only the earliest expiry time istaken into account.By default, the ReaderLifespanQosPolicy is not used and use_lifespan is FALSE.The duration is set to DURATION_INFINITE.This QosPolicy is applicable to a DataReader only, and is mutable even when theDataReader is already enabled. If modified, the new setting will only be applied tosamples that are received after the modification took place.

3.1.3.26 DDS_ShareQosPolicy

Synopsis#include <dds_dcps.h>struct DDS_ShareQosPolicy { DDS_string name, DDS_boolean enable };

DescriptionUsed to share a DataReader between multiple processes.NOTE: This is an OpenSplice-specific QosPolicy, it is not part of the DDSSpecification.

AttributesDDS_string name - The label used to identify the shared Entity.DDS_boolean enable - Controls whether the entity is shared.

114API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

Detailed DescriptionThis QosPolicy allows sharing of entities by multiple processes or threads. Whenthe policy is enabled, the data distribution service will try to look up an existingentity that matches the name supplied in the ShareQosPolicy. A new entity will onlybe created if a shared entity registered under the specified name doesn’t exist yet.Shared Readers can be useful for implementing algorithms like the worker pattern,where a single shared reader can contain samples representing different tasks thatmay be processed in parallel by separate processes. In this algorithm each processesconsumes the task it is going to perform (i.e. it takes the sample represening thattask), thus preventing other processes from consuming and therefore performing thesame task.NOTE: Entities can only be shared between processes if OpenSplice is running infederated mode, because it requires shared memory to communicate between thedifferent processes.By default, the ShareQosPolicy is not used and enable is FALSE. Name must be setto a valid string for the ShareQosPolicy to be valid when enable is set to TRUE.This QosPolicy is applicable to DataReader and Subscriber entities, and cannot bemodified after the DataReader or Subscriber is enabled. Note that a DataReader canonly be shared if its Subscriber is also shared.

3.1.3.27 DDS_ViewKeyQosPolicy

Synopsis#include <dds_dcps.h>struct DDS_ViewKeyQosPolicy { DDS_boolean use_key_list; DDS_StringSeq key_list };

DescriptionUsed to define a set of keys on a DataReaderView.NOTE: This is an OpenSplice-specific QosPolicy, it is not part of the DDSSpecification.

Detailed DescriptionThis QosPolicy is used to set the key list of a DataReaderView. A DataReaderViewallows a different view, defined by this key list, on the data set of the DataReaderfrom which it is created.Opera t ions tha t ope ra te on ins tances o r in s t ance hand les , such aslookup_instance or get_key_value, respect the alternative key-list and workas expected. However, since the mapping of writer instances to reader instances is

115API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

no longer trivial (one writer instance may now map to more than one matchingreader instance and vice versa), a writer instance will no longer be able to fullydetermine the lifecycle of its matching reader instance, nor the value itsview_state and instance_state.In fact, the view sample will always copy the view_state and instance_statevalues from the reader sample to which it is slaved. If both samples preserve a 1 – 1correspondence with respect to their originating instances (this may sometimes bethe case even when an alternative keylist is provided, i.e. when one reader instancenever maps to more than one view instance and vice versa) then the resultinginstance_state and view_state still have a valid semantical meaning. If this1 – 1 correspondence cannot be guaranteed, the resulting instance_state andview_state are semantically meaningless and should not be used to derive anyconclusion regading the lifecycle of a view instance.By default, the DDS_ViewKeyQosPolicy is disabled because use_key_list isset to FALSE.This QosPolicy is applicable to a DataReaderView only, and cannot be changedafter the DataReaderView is created.

3.1.4 DDS_Listener interfaceThis interface is the abstract base interface for all Listener interfaces.Listeners provide a generic mechanism for the Data Distribution Service tonotify the application of relevant asynchronous status change events, such as amissed deadline, violation of a QosPolicy setting, etc. Each DCPS DDS_Entitysupports its own specialized kind of Listener. Listeners are related to changesin communication status. For each DDS_Entity type, one specific Listener isderived from this interface. In the following modules, the following Listeners arederived from this interface:• DDS_DomainParticipantListener• DDS_TopicListener• DDS_PublisherListener• DDS_DataWriterListener• DDS_SubscriberListener• DDS_DataReaderListener.The DDS_Entity type specific Listener interfaces are part of the applicationwhich must implement the interface operations. A user-defined class for theseoperations must be provided by the application which must extend from the specific

116API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

Listener class. All Listener operations must be implemented in theuser-defined class, it is up to the application whether an operation is empty orcontains some functionality.

Figure 11: DCPS Listeners

The base class DDS_Listener does not contain any operations.

3.1.5 Struct DDS_StatusEach concrete DDS_Entity class has a set of DDS_Status attributes and for eachattribute the DDS_Entity class provides an operation to read the value. Changes toDDS_Status attributes will affect associated DDS_StatusCondition and(invoked and associated) Listener objects.The communication statuses whose changes can be communicated to the applicationdepend on the DDS_Entity. The following table shows the relevant statuses foreach DDS_Entity.

Listener(from Infrastructure Module)

<<Interface>>

DataWriterListener

on_liveliness_lost()on_offered_deadline_missed()on_offered_incompatible_qos()on_publication_match()

<<Interface>>DataReaderListener

on_data_available()on_liveliness_changed()on_requested_deadline_missed()on_requested_incompatible_qos()on_sample_lost()on_sample_rejected()on_subscription_match()

<<Interface>>

SubscriberListener

on_data_on_readers()

<<Interface>>

PublisherListener<<Interface>>

TopicListener

on_inconsistent_topic()

<<Interface>>

DomainParticipantListener

117API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

Table 15: Status Description Per DDS_Entity

DDS_Entity Status Name MeaningDDS_Topic DDS_INCONSISTENT_

TOPIC_STATUSAnother DDS_Topic exists with the same namebut with different characteristics.

DDS_ALL_DATA_ DISPOSED_TOPIC_STATUS

All instances of the Topic have been disposed by the dispose_all_data operation on that topic.

DDS_Subscriber DDS_DATA_ON_ READERS_STATUS

New information is available.

DDS_DataReader DDS_SAMPLE_ REJECTED_STATUS

A (received) sample has been rejected.

DDS_LIVELINESS_ CHANGED_STATUS

T h e l i v e l i n e s s o f o n e o r m o r eDDS_DataWriter objects that were writinginstances read through the DDS_DataReaderhas changed. Some DDS_DataWriter havebecome “alive” or “not alive”.

DDS_REQUESTED_ DEADLINE_MISSED_STATUS

The deadline that the DDS_DataReader wase x p e c t i n g t h r o u g h i t sDDS_DeadlineQosPolicy w a s n o trespected for a specific instance.

DDS_REQUESTED_ INCOMPATIBLE_QOS_STATUS

A QosPolicy setting was incompatible withwhat is offered.

DDS_DATA_AVAILABLE_STATUS New information is available.DDS_SAMPLE_LOST_STATUS A sample has been lost (never received).DDS_SUBSCRIPTION_ MATCHED_STATUS

Th e DDS_DataReader h a s f o u n d aDDS_DataWriter t h a t m a t c h e s t h eDDS_Topic and has compatible QoS.

118API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

A DDS_Status a t t r i b u t e c a n b e r e t r i e v e d w i t h t h e o p e r a t i o nget_<status_name>_status . F o r e x a m p l e , t o g e t t h eDDS_InconsistentTopicStatus value, the application must call the operationDDS_Topic_get_inconsistent_topic_status.Conceptually associated with each DDS_Entity communication status is a logicalStatusChangedFlag. This flag indicates whether that particular communicationstatus has changed. The StatusChangedFlag is only conceptual, therefore, it isnot important whether this flag actually exists.For the plain communication DDS_Status, the StatusChangedFlag is initiallyset to FALSE. It becomes TRUE whenever the plain communication DDS_Statuschanges and it is reset to FALSE each time the application accesses the plaincommunication DDS_Status via the proper get_<status_name>_statusoperation on the DDS_Entity.A flag set means that a change has occurred since the last time the application hasread its value.

DDS_DataWriter DDS_LIVELINESS_ LOST_STATUS

The liveliness that the DDS_DataWriter has committed through its DDS_LivelinessQosPolicy was not respected; thus DDS_DataReader objects will consider the DDS_DataWriter as no longer “alive”.

DDS_OFFERED_ DEADLINE_MISSED_STATUS

The deadline that the DDS_DataWriter has committed through its DDS_DeadlineQosPolicy was not respected for a specific instance.

DDS_OFFERED_ INCOMPATIBLE_QOS_STATUS

A QosPolicy setting was incompatible with what was requested.

DDS_PUBLICATION_ MATCHED_STATUS

The DDS_DataWriter has found a DDS_DataReader that matches the DDS_Topic and has compatible QoS.

Table 15: Status Description Per DDS_Entity (continued)

DDS_Entity Status Name Meaning

119API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

Figure 12: DCPS DDS_Status ValuesEach DDS_Status attribute is implemented as a struct and therefore does notprovide any operations. The interface description of these structs is as follows:

/* * struct DDS_<name>Status */

struct DDS_InconsistentTopicStatus { DDS_long total_count; DDS_long total_count_change; };struct DDS_AllDataDisposedTopicStatus { DDS_long total_count; DDS_long total_count_change; }struct DDS_SampleLostStatus { DDS_long total_count; DDS_long total_count_change; };enum DDS_SampleRejectedStatusKind { DDS_NOT_REJECTED, DDS_REJECTED_BY_INSTANCES_LIMIT, DDS_REJECTED_BY_SAMPLES_LIMIT, DDS_REJECTED_BY_SAMPLES_PER_INSTANCE_LIMIT };struct DDS_SampleRejectedStatus { DDS_long total_count; DDS_long total_count_change; DDS_SampleRejectedStatusKind last_reason;

Status

SampleLostStatus

total_count : longtotal_count_change : long

InconsistentTopicStatus

total_count : longtotal_count_change : long

SampleRejectedStatus

total_count : longtotal_count_change : longlast_reason : SampleRejectedStatusKindlast_instance_handle : InstanceHandle_t

PublicationMatchStatus

total_count : longtotal_count_change : longlast_subscription_handle : InstanceHandle_t

LivelinessChangedStatus

active_count : longinactive_count : longactive_count_change : longinactive_count_change : long

OfferedDeadlineMissedStatus

total_count : longtotal_count_change : longlast_instance_handle : InstanceHandle_t

RequestedDeadlineMissedStatus

total_count : longtotal_count_change : longlast_instance_handle : InstanceHandle_t

SubscriptionMatchStatus

total_count : longtotal_count_change : longlast_publication_handle : InstanceHandle_t

LivelinessLostStatus

total_counttotal_count_change

OfferedIncompatibleQosStatus

total_counttotal_count_changelast_policy_idpolicies [*]

RequestedIncompatibeQosStatus

total_counttotal_count_changelast_policy_idpolicies [*]

QosPolicyCount

policy_idcount

120API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

DDS_InstanceHandle_t last_instance_handle; };struct DDS_LivelinessLostStatus { DDS_long total_count; DDS_long total_count_change; };struct DDS_LivelinessChangedStatus { DDS_long alive_count; DDS_long not_alive_count; DDS_long alive_count_change; DDS_long not_alive_count_change; DDS_InstanceHandle_t last_publication_handle; };struct DDS_OfferedDeadlineMissedStatus { DDS_long total_count; DDS_long total_count_change; DDS_InstanceHandle_t last_instance_handle; };struct DDS_RequestedDeadlineMissedStatus { DDS_long total_count; DDS_long total_count_change; DDS_InstanceHandle_t last_instance_handle; };struct DDS_OfferedIncompatibleQosStatus { DDS_long total_count; DDS_long total_count_change; DDS_QosPolicyId_t last_policy_id; DDS_QosPolicyCountSeq policies; };struct DDS_RequestedIncompatibleQosStatus { DDS_long total_count; DDS_long total_count_change; DDS_QosPolicyId_t last_policy_id; DDS_QosPolicyCountSeq policies; };struct DDS_PublicationMatchedStatus { DDS_long total_count; DDS_long total_count_change; DDS_long current_count; DDS_long current_count_change; DDS_InstanceHandle_t last_subscription_handle; };struct DDS_SubscriptionMatchedStatus { DDS_long total_count; DDS_long total_count_change; DDS_long current_count; DDS_long current_count_change; DDS_InstanceHandle_t last_publication_handle; };

/* * implemented API operations * <no operations> */

The sections describe the usage of each DDS_<name>Status struct.

121API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

3.1.5.1 DDS_InconsistentTopicStatus

Synopsis#include <dds_dcps.h>struct DDS_InconsistentTopicStatus

{ DDS_long total_count; DDS_long total_count_change; };

DescriptionThis struct contains the statistics about attempts to create other DDS_Topics withthe same name but with different characteristics.

AttributesDDS_long total_count - the total detected cumulative count of DDS_Topic

creations, whose name matches the DDS_Topic to which this DDS_Status isattached and whose characteristics are inconsistent.

DDS_long total_count_change - the change in total_count since the lasttime the Listener was called or the DDS_Status was read.

Detailed DescriptionThis struct contains the statistics about attempts to create other DDS_Topics withthe same name but with different characteristics.The attribute total_count holds the total cumulative count of DDS_Topiccreations, whose name matches the DDS_Topic to which this DDS_Status isattached and whose characteristics are inconsistent.The attribute total_count_change holds the incremental number of inconsistentDDS_Topics, since the last time the Listener was called or the DDS_Status wasread.

3.1.5.2 DDS_LivelinessChangedStatus

Synopsis#include <dds_dcps.h>struct DDS_LivelinessChangedStatus

{ DDS_long alive_count; DDS_long not_alive_count; DDS_long alive_count_change; DDS_long not_alive_count_change; DDS_InstanceHandle_t last_publication_handle; };

DescriptionThis struct contains the statistics about whether the liveliness of one or moreconnected DDS_DataWriter objects has changed.

122API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

AttributesDDS_long alive_count - the total count of currently alive DDS_DataWriter

objects that write the topic read by the DDS_DataReader to which thisDDS_Status is attached.

DDS_long not_alive_count - the total count of currently not aliveDDS_DataWriter objects that wrote the topic read by the DDS_DataReaderto which this DDS_Status is attached.

DDS_long alive_count_change - the change in alive_count since the lasttime the Listener was called or the DDS_Status was read.

DDS_long not_alive_count_change - the change in not_alive_countsince the last time the Listener was called or the DDS_Status was read.

DDS_InstanceHandle_t last_publication_handle - handle to the lastDDS_DataWriter whose change in liveliness caused this status to change.

Detailed DescriptionThis struct contains the statistics about whether the liveliness of one or moreconnected DDS_DataWriter objects that were writing instances read through theDDS_DataReader has changed. In other words, some DDS_DataWriters havebecome “alive” or “not alive”.The attribute alive_count holds the total number of currently aliveDDS_DataWriter objects that write the topic read by the DDS_DataReader towhich this DDS_Status is attached. This count increases when a newly matchedDDS_DataWriter asser ts i t s l ivel iness for the f i rs t t ime or when aDDS_DataWriter previously considered to be not alive reasserts its liveliness. Thecount decreases when a DDS_DataWriter considered alive fails to assert itsliveliness and becomes not alive, whether because it was deleted normally or forsome other reason.The attribute not_alive_count holds the total count of currently not aliveDDS_DataWriters that wrote the topic read by the DDS_DataReader to whichthis DDS_Status is attached, and that are no longer asserting their liveliness. Thiscount increases when a DDS_DataWriter considered alive fails to assert itsliveliness and becomes not alive for some reason other than the normal deletion ofthat DDS_DataWriter. It decreases when a previously not alive DDS_DataWritereither reasserts its liveliness or is deleted normally.The attribute alive_count_change holds the change in alive_count since thelast time the Listener was called or the DDS_Status was read.T h e a t t r i b u t e not_alive_count_change h o l d s t h e c h a n g e i nnot_alive_count since the last time the Listener was called or theDDS_Status was read.

123API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

The attribute last_publication_handle contains the instance handle to theDDS_PublicationBuiltinTopicData instance that represents the lastdatawriter whose change in liveliness caused this status to change. Be aware thatt h i s h a n d l e b e l o n g s t o an o th er d a t a r e a d e r, t h eDDS_PublicationBuiltinTopicDataDataReader in the builtin-subscriber,and has no meaning in the context of the datareader from which theDDS_LivelinessChangedStatus was obtained. If the builtin-subscriber has note x p l i c i t l y b e e n o b t a i n e d u s i n gDDS_DomainParticipant_get_builtin_subscriber, then there is noDDS_PublicationBuiltinTopicDataDataReader as well, in which case thelast_publication_handle will be set to DDS_HANDLE_NIL.

3.1.5.3 DDS_LivelinessLostStatus

Synopsis#include <dds_dcps.h>struct DDS_LivelinessLostStatus

{ DDS_long total_count; DDS_long total_count_change; };

DescriptionThis struct contains the statist ics about whether the l iveliness of theDDS_DataWriter to which this DDS_Status is attached has been committedthrough its DDS_LivelinessQosPolicy.

AttributesDDS_long total_count - the tota l cumulat ive count of t imes the

DDS_DataWriter to which this DDS_Status is attached failed to activelysignal its liveliness within the offered liveliness period.

DDS_long total_count_change - the change in total_count since the lasttime the Listener was called or the DDS_Status was read.

Detailed DescriptionThis struct contains the statist ics about whether the l iveliness of theDDS_DataWriter to which this DDS_Status is attached has been committedthrough its DDS_LivelinessQosPolicy. In other words, whether theDDS_DataWriter failed to actively signal its liveliness within the offeredliveliness period. In such a case, the connected DDS_DataReader objects willconsider the DDS_DataWriter as no longer “alive”.

124API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

The attribute total_count holds the total cumulative number of times that thepreviously-alive DDS_DataWriter became not alive due to a failure to activelysignal its liveliness within its offered liveliness period. This count does not changewhen an already not alive DDS_DataWriter simply remains not alive for anotherliveliness period.The attribute total_count_change holds the change in total_count since thelast time the Listener was called or the DDS_Status was read.

3.1.5.4 DDS_OfferedDeadlineMissedStatus

Synopsis#include <dds_dcps.h>struct DDS_OfferedDeadlineMissedStatus

{ DDS_long total_count; DDS_long total_count_change; DDS_InstanceHandle_t last_instance_handle; };

DescriptionThis struct contains the statistics about whether the deadline that theDDS_DataWriter to which this DDS_Status is attached has committed throughits DDS_DeadlineQosPolicy, was not respected for a specific instance.

AttributesDDS_long total_count - the tota l cumulat ive count of t imes the

DDS_DataWriter to which this DDS_Status is attached failed to write withinits offered deadline.

DDS_long total_count_change - the change in total_count since the lasttime the Listener was called or the DDS_Status was read.

DDS_InstanceHandle_t last_instance_handle - the handle to the lastinstance in the DDS_DataWriter to which this DDS_Status is attached, forwhich an offered deadline was missed.

Detailed DescriptionThis struct contains the statistics about whether the deadline that theDDS_DataWriter to which this DDS_Status is attached has committed throughits DDS_DeadlineQosPolicy, was not respected for a specific instance.The attribute total_count holds the total cumulative number of offered deadlineperiods elapsed during which the DDS_DataWriter to which this DDS_Status isattached failed to provide data. Missed deadlines accumulate; that is, each deadlineperiod the total_count will be incremented by one.

125API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

The attribute total_count_change holds the change in total_count since thelast time the Listener was called or the DDS_Status was read.The attribute last_instance_handle holds the handle to the last instance in theDDS_DataWriter to which this DDS_Status is attached, for which an offereddeadline was missed.

3.1.5.5 DDS_OfferedIncompatibleQosStatus

Synopsis#include <dds_dcps.h>struct DDS_OfferedIncompatibleQosStatus

{ DDS_long total_count; DDS_long total_count_change; QosPolicyId_t last_policy_id; QosPolicyCountSeq policies; };

DescriptionThis struct contains the statistics about whether an offered QosPolicy setting wasincompatible with the requested QosPolicy setting.

AttributesDDS_long total_count - the total cumulative count of DDS_DataReader

objects discovered by the DDS_DataWriter with the same DDS_Topic andPartition and with a requested DDS_DataReaderQos that was incompatiblewith the one offered by the DDS_DataWriter.

DDS_long total_count_change - the change in total_count since the lasttime the Listener was called or the DDS_Status was read.

QosPolicyId_t last_policy_id - the id of one of the QosPolicy settingsthat was found to be incompatible with what was offered, the last time anincompatibility was detected.

QosPolicyCountSeq policies - a list containing for each QosPolicy the totalnumber of times that the concerned DDS_DataWriter discovered aDDS_DataReader f o r t he s a me DDS_Topic a nd a r eques t e dDDS_DataReaderQos that is incompatible with the one offered by theDDS_DataWriter.

Detailed DescriptionThis struct contains the statistics about whether an offered QosPolicy setting wasincompatible with the requested QosPolicy setting.The Request/Offering mechanism is applicable between:

126API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

• the DDS_DataWriter and the DDS_DataReader. If the QosPolicy settingsbetween DDS_DataWriter and DDS_DataReader are incompatible, nocommunication between them is established. In addition the DDS_DataWriterwill be informed via a DDS_REQUESTED_INCOMPATIBLE_QOS status change andthe DDS_DataReader will be informed via anDDS_OFFERED_INCOMPATIBLE_QOS status change.

• the DDS_DataWriter and the Durability Service (as a built-inDDS_DataReader). If the QosPolicy settings between DDS_DataWriter andthe Durability Service are inconsistent, no communication between them isestablished. In that case data published by the DDS_DataWriter will not bemaintained by the service and as a consequence will not be available for latejoining DDS_DataReaders. The QosPolicy of the Durability Service in the roleof DDS_DataReader is specified by the DDS_DurabilityServiceQosPolicyin the DDS_Topic.

• the Durability Service (as a built-in DDS_DataWriter) and theDDS_DataReader. If the QosPolicy settings between the Durability Serviceand the DDS_DataReader are inconsistent, no communication between them isestablished. In that case the Durability Service will not publish historical data tolate joining DDS_DataReaders. The QosPolicy of the Durability Service in therole of DDS_DataWriter is specified by theDDS_DurabilityServiceQosPolicy in the DDS_Topic.

The attribute total_count holds the total cumulative count of DDS_DataReaderobjects discovered by the DDS_DataWriter with the same DDS_Topic and arequested DDS_DataReaderQos that was incompatible with the one offered by theDDS_DataWriter.The attribute total_count_change holds the change in total_count since thelast time the Listener was called or the DDS_Status was read.The attribute last_policy_id holds the id of one of the QosPolicy settings thatwas found to be incompatible with what was offered, the last t ime anincompatibility was detected.The attribute policies holds a list containing for each QosPolicy the totalnumber of times that the concerned DDS_DataWriter discovered an incompatibleDDS_DataReader for the same DDS_Topic. Each element in the list represents acounter for a different QosPolicy, identified by a corresponding unique indexnumber. A named list of all index numbers is expressed as a set of constants in theAPI. See Table 16: below for an overview of all these constants.

127API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

3.1.5.6 DDS_PublicationMatchedStatus

Synopsis#include <dds_dcps.h>struct DDS_PublicationMatchedStatus

{ DDS_long total_count; DDS_long total_count_change; DDS_long current_count; DDS_long current_count_change;

Table 16: Overview of All Named QosPolicy Indexes

Index Name Index ValueDDS_INVALID_QOS_POLICY_ID 0

DDS_USERDATA_QOS_POLICY_ID 1

DDS_DURABILITY_QOS_POLICY_ID 2

DDS_PRESENTATION_QOS_POLICY_ID 3

DDS_DEADLINE_QOS_POLICY_ID 4

DDS_LATENCYBUDGET_QOS_POLICY_ID 5

DDS_OWNERSHIP_QOS_POLICY_ID 6

DDS_OWNERSHIPSTRENGTH_QOS_POLICY_ID 7

DDS_LIVELINESS_QOS_POLICY_ID 8

DDS_TIMEBASEDFILTER_QOS_POLICY_ID 9

DDS_PARTITION_QOS_POLICY_ID 10

DDS_RELIABILITY_QOS_POLICY_ID 11

DDS_DESTINATIONORDER_QOS_POLICY_ID 12

DDS_HISTORY_QOS_POLICY_ID 13

DDS_RESOURCELIMITS_QOS_POLICY_ID 14

DDS_ENTITYFACTORY_QOS_POLICY_ID 15

DDS_WRITERDATALIFECYCLE_QOS_POLICY_ID 16

DDS_READERDATALIFECYCLE_QOS_POLICY_ID 17

DDS_TOPICDATA_QOS_POLICY_ID 18

DDS_GROUPDATA_QOS_POLICY_ID 19

DDS_TRANSPORTPRIORITY_QOS_POLICY_ID 20

DDS_LIFESPAN_QOS_POLICY_ID 21

DDS_DURABILITYSERVICE_QOS_POLICY_ID 22

128API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

DDS_InstanceHandle_t last_subscription_handle; };

DescriptionThis struct contains the statistics about the discovered number of matchingDataReaders currently connected to the owner of this status, and of the cumulativenumber of DataReaders that has connected to the owner of this status over time.

AttributesDDS_long total_count - Total cumulative count of DataReaders compatible

with the concerned DataWriter.DDS_long total_count_change - The change in total_count since the last time

the Status was read.DDS_long current_count - Total count of DataReaders that are currently

available and compatible with the DataWriter.DDS_long current_count_change - The change in current_count since the

last time the Status was read.DDS_InstanceHandle_t last_subscription_handle - Handle to the last

DataReader that matched the DataWriter causing the status to change.

Detailed DescriptionThis struct contains the statistics about the discovered number of DataReaders thatare compatible with the DataWriter to which the Status is attached. DataReader andDataWriter are compatible if they use the same Topic and if the QoS requested bythe DataReader is compatible with that offered by the DataWriter. A DataReaderwill automatically connect to a matching DataWriter, but will disconnect when thatDataReader is deleted, when either changes its QoS into an incompatible value, orwhen either puts i ts matching counterpart on its ignore-list using theignore_subscription or ignore_publication operations on theDomainParticipant.The total_count includes DataReaders that have already been disconnected,while in the current_count only the currently connected DataReaders areconsidered.

3.1.5.7 DDS_RequestedDeadlineMissedStatus

Synopsis#include <dds_dcps.h>struct DDS_RequestedDeadlineMissedStatus

{ DDS_long total_count; DDS_long total_count_change; DDS_InstanceHandle_t last_instance_handle; };

129API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

DescriptionThis struct contains the statistics about whether the deadline that theDDS_DataReader to which this DDS_Status is attached was expecting through itsDDS_DeadlineQosPolicy, was not respected for a specific instance.

AttributesDDS_long total_count - the total cumulative count of the missed deadlines

detected for any instance read by the DDS_DataReader to which thisDDS_Status is attached.

DDS_long total_count_change - the change in total_count since the lasttime the Listener was called or the DDS_Status was read.

DDS_InstanceHandle_t last_instance_handle - the handle to the lastinstance in the DDS_DataReader to which this DDS_Status is attached forwhich a missed deadline was detected.

Detailed DescriptionThis struct contains the statistics about whether the deadline that theDDS_DataReader to which this DDS_Status is attached was expecting through itsDDS_DeadlineQosPolicy, was not respected for a specific instance. Misseddeadlines accumulate, that is, each deadline period the total_count will beincremented by one for each instance for which data was not received.The attribute total_count holds the total cumulative count of the misseddeadlines detected for any instance read by the DDS_DataReader.The attribute total_count_change holds the change in total_count since thelast time the Listener was called or the DDS_Status was read.The attribute last_instance_handle holds the handle to the last instance in theDDS_DataReader for which a missed deadline was detected.

3.1.5.8 DDS_RequestedIncompatibleQosStatus

Synopsis#include <dds_dcps.h>struct DDS_RequestedIncompatibleQosStatus

{ DDS_long total_count; DDS_long total_count_change; QosPolicyId_t last_policy_id; QosPolicyCountSeq policies; };

DescriptionThis struct contains the statistics about whether a requested QosPolicy setting wasincompatible with the offered QosPolicy setting.

130API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

AttributesDDS_long total_count - holds the total cumulative count of DDS_DataWriter

objects, discovered by the DDS_DataReader to which this DDS_Status isattached, with the same DDS_Topic and an offered DDS_DataWriterQos thatwas incompatible with the one requested by the DDS_DataReader.

DDS_long total_count_change - holds the change in total_count since thelast time the Listener was called or the DDS_Status was read.

QosPolicyId_t last_policy_id - holds the DDS_<name>_QOS_POLICY_IDof one of the QosPolicies that was found to be incompatible with what wasrequested, the last time an incompatibility was detected.

QosPolicyCountSeq policies - a list containing (for each QosPolicy) thetotal number of times that the concerned DDS_DataReader discovered aDDS_DataWriter w i t h t h e s a m e DDS_Topic a n d a n o ff e r e dDDS_DataWriterQos that is incompatible with the one requested by theDDS_DataReader.

Detailed DescriptionThis struct contains the statistics about whether a requested QosPolicy setting wasincompatible with the offered QosPolicy setting.The Request/Offering mechanism is applicable between:• the DDS_DataWriter and the DDS_DataReader. If the QosPolicy settings

between DDS_DataWriter and DDS_DataReader are incompatible, nocommunication between them is established. In addition the DDS_DataWriterwill be informed via a DDS_REQUESTED_INCOMPATIBLE_QOS status change andthe DDS_DataReader will be informed via anDDS_OFFERED_INCOMPATIBLE_QOS status change.

• the DDS_DataWriter and the Durability Service (as a built-inDDS_DataReader). If the QosPolicy settings between DDS_DataWriter andthe Durability Service are inconsistent, no communication between them isestablished. In that case data published by the DDS_DataWriter will not bemaintained by the service and as a consequence will not be available for latejoining DDS_DataReaders. The QosPolicy of the Durability Service in the roleof DDS_DataReader is specified by the DDS_DurabilityServiceQosPolicyin the DDS_Topic.

• the Durability Service (as a built-in DDS_DataWriter) and theDDS_DataReader. If the QosPolicy settings between the Durability Serviceand the DDS_DataReader are inconsistent, no communication between them isestablished. In that case the Durability Service will not publish historical data to

131API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

late joining DDS_DataReaders. The QosPolicy of the Durability Service in therole of DDS_DataWriter is specified by theDDS_DurabilityServiceQosPolicy in the DDS_Topic.

The attribute total_count holds the total cumulative count of DDS_DataWriterobjects discovered by the DDS_DataReader with the same DDS_Topic and anoffered DDS_DataWriterQos that was incompatible with the one requested by theDDS_DataReader.The attribute total_count_change holds the change in total_count since thelast time the Listener was called or the DDS_Status was read.The attribute last_policy_id holds the DDS_<name>_QOS_POLICY_ID of oneof the QosPolicies that was found to be incompatible with what was requested,the last time an incompatibility was detected.The attribute policies holds a list containing for each QosPolicy: the totalnumber of times that the concerned DDS_DataReader discovered an incompatibleDDS_DataWriter for the same DDS_Topic. Each element in the list represents acounter for a different QosPolicy, identified by a corresponding unique indexnumber. A named list of all index numbers is expressed as a set of constants in theAPI. See Table 16, Overview of All Named QosPolicy Indexes, on page 128 for anoverview of all these constants.

3.1.5.9 DDS_SampleLostStatus

Synopsis#include <dds_dcps.h>struct DDS_SampleLostStatus

{ DDS_long total_count; DDS_long total_count_change; };

DescriptionThis struct contains the statistics about whether a sample has been lost (neverreceived).

AttributesDDS_long total_count - holds the total cumulative count of all samples lost

across all instances of data published under the DDS_Topic.DDS_long total_count_change - holds the change in total_count since the

last time the Listener was called or the DDS_Status was read.

132API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

Detailed DescriptionThis struct contains the statistics about whether a sample has been lost (neverreceived). The status is independent of the differences in instances, in other words, itincludes all samples lost across all instances of data published under theDDS_Topic.total_count holds the total cumulative count of all samples lost across allinstances of data published under the DDS_Topic.total_count_change holds the change in total_count since the last time theListener was called or the DDS_Status was read.

3.1.5.10 DDS_SampleRejectedStatus

Synopsis#include <dds_dcps.h>

enum DDS_SampleRejectedStatusKind { DDS_NOT_REJECTED, DDS_REJECTED_BY_INSTANCES_LIMIT, DDS_REJECTED_BY_SAMPLES_LIMIT, DDS_REJECTED_BY_SAMPLES_PER_INSTANCE_LIMIT };

struct DDS_SampleRejectedStatus { DDS_long total_count; DDS_long total_count_change; DDS_SampleRejectedStatusKind last_reason; DDS_InstanceHandle_t last_instance_handle; };

DescriptionThis struct contains the statistics about samples that have been rejected.

AttributesDDS_long total_count - holds the total cumulative count of samples rejected by

the DDS_DataReader to which this DDS_Status is attached.DDS_long total_count_change - holds the change in total_count since the

last time the Listener was called or the DDS_Status was read.DDS_SampleRejectedStatusKind last_reason - holds the reason for

rejecting the last sample.DDS_InstanceHandle_t last_instance_handle - holds the handle to the

instance which would have updated by the last sample that was rejected.

Detailed DescriptionThis struct contains the statistics about whether a received sample has been rejected.

133API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

The attribute total_count holds the total cumulative count of samples rejected bythe DDS_DataReader to which this DDS_Status is attached.The attribute total_count_change holds the change in total_count since thelast time the Listener was called or the DDS_Status was read.The attribute last_reason holds the reason for rejecting the last sample. Theattribute can have the following values:• DDS_NOT_REJECTED - no sample has been rejected yet.• DDS_REJECTED_BY_INSTANCES_LIMIT - the sample was rejected because it

would exceed the maximum number of instances set by theDDS_ResourceLimitsQosPolicy.

• DDS_REJECTED_BY_SAMPLES_LIMIT - the sample was rejected because itwould exceed the maximum number of samples set by theDDS_ResourceLimitsQosPolicy.

• DDS_REJECTED_BY_SAMPLES_PER_INSTANCE_LIMIT - the sample wasrejected because it would exceed the maximum number of samples per instanceset by the DDS_ResourceLimitsQosPolicy.

The attribute last_instance_handle holds the handle to the instance whichwould have updated by the last sample that was rejected.

3.1.5.11 DDS_SubscriptionMatchedStatus

Synopsis#include <dds_dcps.h>struct DDS_SubscriptionMatchedStatus

{ DDS_long total_count; DDS_long total_count_change; DDS_long current_count; DDS_long current_count_change; DDS_InstanceHandle_t last_publication_handle; };

DescriptionThis struct contains the statistics about the discovered number of matchingDataWriters currently connected to the owner of this status, and of the cumulativenumber of DataWriters that has connected to the owner of this status over time.

AttributesDDS_long total_count - Total cumulative count of DataWriters compatible

with the concerned DataReader.DDS_long total_count_change - The change in total_count since the last

time the Status was read.

134API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

DDS_long current_count - Total count of DataWriters that are currentlyavailable and compatible with the DataWriter.

DDS_long current_count_change - The change in current_count since thelast time the Status was read.

DDS_InstanceHandle_t last_publication_handle - Handle to the lastDataWriter that matched the DataReader causing the status to change.

Detailed DescriptionThis struct contains the statistics about the discovered number of DataWriters thatare compatible with the DataReader to which the Status is attached. DataWriter andDataReader are compatible if they use the same Topic and if the QoS requested bythe DataReader is compatible with that offered by the DataWriter. A DataWriter willautomatically connect to a matching DataReader, but will disconnect when thatDataWriter is deleted, when either changes its QoS into an incompatible value, orwhen either puts i ts matching counterpart on its ignore-list using theignore_subscription or ignore_publication operations on theDomainParticipant.The total_count includes DataWriters that have already been disconnected,while in the current_count only the currently connected DataWriters areconsidered.

3.1.5.12 DDS_AllDataDisposedTopicStatus

Synopsis#include <dds_dcps.h>struct DDS_AllDataDisposedTopicStatus { DDS_long total_count DDS_long total_count_change }

DescriptionT h i s s t r u c t c on t a in s t h e s t a t i s t i c s abou t t he occ u rence o f t heDDS_ALL_DATA_DISPOSED_TOPIC_STATUS event on the Topic to which thisStatus is attached.

AttributesDDS_long total_count - the to ta l detected cumulat ive count of

ALL_DATA_DISPOSED_TOPIC_STATUS events.DDS_long total_count_change - the change in total_count since the last

time the Status was read.

135API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

Detailed DescriptionT h i s s t r u c t c on t a in s t h e s t a t i s t i c s abou t t he occ u rence o f t heDDS_ALL_DATA_DISPOSED_TOPIC_STATUS event on the Topic to which thisStatus is attached. The Status is directly related to the invocation of theDDS_Topic_dispose_all_data() operation. Statistics are only kept when allinstances are disposed using this operation, not when instances are disposedseperately by individual dispose calls.

3.1.6 Class DDS_WaitSetA DDS_WaitSet object allows an application to wait until one or more of theattached DDS_Condition objects evaluates to TRUE or until the timeout expires.The DDS_WaitSet has no factory and must be created by the application. It isdirectly created as an object by using DDS_WaitSet constructors.

Figure 13: DCPS DDS_WaitSets

The interface description of this class is as follows:/* * interface DDS_WaitSet *//* * implemented API operations */

DDS_WaitSet DDS_WaitSet__alloc (void);DDS_ReturnCode_t DDS_WaitSet_wait (DDS_WaitSet _this,

DDS_ConditionSeq *active_conditions, const DDS_Duration_t *timeout);

DDS_ReturnCode_t DDS_WaitSet_attach_condition (DDS_WaitSet _this,

const DDS_Condition cond);DDS_ReturnCode_t DDS_WaitSet_detach_condition (DDS_WaitSet _this,

const DDS_Condition cond);DDS_ReturnCode_t

Condition

get_trigger_value()

WaitSet

attach_condition()detach_condition()get_conditions()wait()

** **

136API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

DDS_WaitSet_get_conditions (DDS_WaitSet _this,

DDS_ConditionSeq *attached_conditions);

The following sections describe the usage of all DDS_WaitSet operations.

3.1.6.1 DDS_WaitSet__alloc

Synopsis#include <dds_dcps.h>DDS_WaitSet DDS_WaitSet__alloc (void);

DescriptionThis operation creates a new DDS_WaitSet.

Parameters<none>

Return ValueDDS_WaitSet - handle to the newly-created DDS_WaitSet. In case of an error, a

DDS_OBJECT_NIL pointer is returned.

Detailed DescriptionThis operation creates a new DDS_WaitSet. The DDS_WaitSet must be createdusing this operation. In other words, the application is not allowed to declare anobject of type DDS_WaitSet. When the application wants to release theDDS_WaitSet it must be released using DDS_free.In case there are insufficient resources available to allocate the DDS_WaitSet, aDDS_OBJECT_NIL pointer is returned instead.

3.1.6.2 DDS_WaitSet_attach_condition

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_WaitSet_attach_condition (DDS_WaitSet _this, const DDS_Condition cond);

DescriptionThis operation attaches a DDS_Condition to the DDS_WaitSet.

137API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

Parametersin DDS_WaitSet _this - the DDS_WaitSet object on which the operation is

operated.in const DDS_Condition cond - a pointer to a DDS_Condition.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation attaches a DDS_Condition to the DDS_WaitSet. The parametercond must be either a DDS_ReadCondition , DDS_QueryCondition ,DDS_StatusCondition or DDS_GuardCondition. To get this parameter see:• DDS_ReadCondition created by

DDS_DataReader_create_readcondition• DDS_QueryCondition created by

DDS_DataReader_create_querycondition• DDS_StatusCondition retrieved by

DDS_<Entity>_get_statuscondition on an DDS_<Entity>• DDS_GuardCondition created by the C operation

DDS_GuardCondition__alloc.When a DDS_GuardCondition is initially created, the trigger_value is FALSE.When a DDS_Condition, whose trigger_value evaluates to TRUE, is attachedt o a DDS_WaitSet t h a t i s c u r r e n t l y b e i n g w a i t e d on (u s in g t h eDDS_WaitSet_wait operation), the DDS_WaitSet will unblock immediately.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the DDS_Condition is attached to the DDS_WaitSet.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter cond is not a validDDS_Condition.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

138API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

3.1.6.3 DDS_WaitSet_detach_condition

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_WaitSet_detach_condition (DDS_WaitSet _this, const DDS_Condition cond)

DescriptionThis operation detaches a DDS_Condition from the DDS_WaitSet.

Parametersin DDS_WaitSet _this - the DDS_WaitSet object on which the operation is

operated.in const DDS_Condition cond - a pointer to a DDS_Condition in the

DDS_WaitSet.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionThis operation detaches a DDS_Condition from the DDS_WaitSet. If theDDS_Condition was not attached to this DDS_WaitSet, the operation returnsDDS_RETCODE_PRECONDITION_NOT_MET.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the DDS_Condition is detached from the DDS_WaitSet.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter cond is not a validDDS_Condition.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

139API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

• DDS_RETCODE_PRECONDITION_NOT_MET - the DDS_Condition was notattached to this DDS_WaitSet.

3.1.6.4 DDS_WaitSet_get_conditions

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_WaitSet_get_conditions (DDS_WaitSet _this, DDS_ConditionSeq *attached_conditions);

DescriptionThis operation retrieves the list of attached conditions.

Parametersin DDS_WaitSet _this - the DDS_WaitSet object on which the operation is

operated.inout DDS_ConditionSeq *attached_conditions - the inout parameter

attached_conditions is a sequence, which is used to pass the list ofattached conditions.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation retrieves the list of attached conditions in the DDS_WaitSet. Theparameter attached_conditions is a pointer to a sequence which afterwardswill point to the sequence of attached conditions. The attached_conditionssequence and its buffer may be pre-allocated by the application and therefore muste i t h e r b e r e - u s ed i n a s u b s e q uen t i nv oc a t i o n o f t h eDDS_WaitSet_get_conditions operation or be released by calling DDS_freeon the returned attached_conditions. If the pre-allocated sequence is not bigenough to hold the number of attached DDS_Conditions, the sequence willautomatically be (re-)allocated to fit the required size. The resulting sequence willeither be an empty sequence, meaning there were no conditions attached, or willcon t a in a l i s t o f DDS_ReadCondition , DDS_QueryCondition ,DDS_StatusCondition and DDS_GuardCondition. These conditionspreviously have been attached by DDS_WaitSet_attach_condition and werecreated by there respective create operation:

140API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

• DDS_ReadCondition created by DDS_DataReader_create_readcondition

• DDS_QueryCondition created by DDS_DataReader_create_querycondition

• DDS_StatusCondition retrieved by DDS_<Entity>_get_statuscondition on an DDS_<Entity>

• DDS_GuardCondition created by the C operation DDS_GuardCondition__alloc.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the list of attached conditions is returned• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

3.1.6.5 DDS_WaitSet_wait

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_WaitSet_wait (DDS_WaitSet _this, DDS_ConditionSeq *active_conditions, const DDS_Duration_t *timeout)

DescriptionThis operation allows an application thread to wait for the occurrence of at least oneof the conditions that is attached to the DDS_WaitSet.

Parametersin DDS_WaitSet _this - the DDS_WaitSet object on which the operation is

operated.inout DDS_ConditionSeq *active_conditions - a sequence which is used

to pass the list of all the attached conditions that have a trigger_value ofTRUE.

141API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

in const DDS_Duration_t *timeout - the maximum duration to block forthe DDS_WaitSet_wait, after which the application thread is unblocked. Thespecial constant DDS_DURATION_INFINITE can be used when the maximumwaiting time does not need to be bounded.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_TIMEOUTor DDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionThis operation allows an application thread to wait for the occurrence of at least oneof the conditions to evaluate to TRUE that is attached to the DDS_WaitSet. If allof the conditions attached to the DDS_WaitSet have a trigger_value of FALSE,the DDS_WaitSet_wait operation will block the calling thread. The result of theoperation is the continuation of the application thread after which the result is left inactive_conditions. This is a sequence, which will contain the list of all thea t t a c h e d c o n d i t i o n s t h a t h a v e a trigger_value o f TRUE . T h eactive_conditions sequence and its buffer may be pre-allocated by theapplication and therefore must either be re-used in a subsequent invocation of theDDS_WaitSet_wait operation or be released by calling DDS_free on the returnedactive_conditions. If the pre-allocated sequence is not big enough to hold thenumber of triggered DDS_Conditions, the sequence will automatically be(re-)allocated to fit the required size. The parameter timeout specifies themaximum duration for the DDS_WaitSet_wait to block the calling applicationthread (when none of the attached conditions has a trigger_value of TRUE). Intha t c a se t he r e tu rn va lue i s DDS_RETCODE_TIMEOUT a n d t h eactive_conditions sequence is left empty. Since it is not allowed for more thanone application thread to be waiting on the same DDS_WaitSet, the operationreturns immediately with the value DDS_RETCODE_PRECONDITION_NOT_METwhen the DDS_WaitSet_wait operation is invoked on a DDS_WaitSet whichalready has an application thread blocking on it.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - at least one of the attached conditions has atrigger_value of TRUE.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.

142API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_TIMEOUT - the timeout has elapsed without any of the attachedconditions becoming TRUE.

• DDS_RETCODE_PRECONDITION_NOT_MET - the DDS_WaitSet already has anapplication thread blocking on it.

3.1.7 Class DDS_ConditionThis class is the base class for all the conditions that may be attached to aDDS_WaitSet. This base class is specialized in three classes by the DataDistribution Service: DDS_GuardCondition, DDS_StatusCondition andDDS_ReadCondition (also there is a DDS_QueryCondition which is aspecialized DDS_ReadCondition).Each DDS_Condition has a trigger_value that can be TRUE or FALSE and isset by the Data Distribution Service (except a DDS_GuardCondition) dependingon the evaluation of the DDS_Condition.

143API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

Figure 14: DCPS DDS_ConditionsThe interface description of this class is as follows: /*

* interface DDS_Condition */ /* * implemented API operations */

DDS_boolean DDS_Condition_get_trigger_value (DDS_Condition _this);

The next paragraph describes the usage of the DDS_Condition operation.

3.1.7.1 DDS_Condition_get_trigger_value

Synopsis#include <dds_dcps.h>

Condition

get_trigger_value()

QueryCondition

get_query_parameters()get_query_expression()set_query_parameters()

DataReader

ReadCondition

get_datareader()get_instance_state_mask()get_sample_state_mask()get_view_state_mask()

1

*

1

*

GuardCondition

set_trigger_value()

Entity

enable()<<abstract>> get_listener()<<abstract>> get_qos()get_status_changes()get_statuscondition()<<abstract>> set_listener()<<abstract>> set_qos()

StatusCondition

get_enabled_statuses()get_entity()set_enabled_statuses()

11

entity

0..10..1statuscondition

DataWriter

PublisherSubscriber

Topic

DomainParticipant

DomainEntity

<<create>>

<<create>>

144API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

DDS_boolean DDS_Condition_get_trigger_value (DDS_Condition _this);

DescriptionThis operation returns the trigger_value of the DDS_Condition.

Parametersin DDS_Condition _this - the DDS_Condition object on which the

operation is operated.

Return ValueDDS_boolean - the trigger_value.

Detailed DescriptionA DDS_Condition has a trigger_value that can be TRUE or FALSE and is setby the Data Distribution Service (except a DDS_GuardCondition). This operationreturns the trigger_value of the DDS_Condition.

3.1.8 Class DDS_GuardConditionA DDS_GuardCondition object is a specific DDS_Condition whosetrigger_value is completely under the control of the application. TheDDS_GuardCondition has no factory and must be created by the application. TheDDS_GuardCondition is direct ly created as an object by using theDDS_GuardCondition constructor. When a DDS_GuardCondition is initiallyc r e a t e d , t h e trigger_value i s FALSE . Th e p u rp ose o f t h eDDS_GuardCondition is to provide the means for an application to manuallyw a k e u p a DDS_WaitSet . Th i s i s a c c o m p l i s h e d b y a t t a c h in g t h eDDS_GuardCondition to the Waitset and setting the trigger_value bymeans of the DDS_GuardCondition_set_trigger_value operation.The interface description of this class is as follows:

/* * interface DDS_GuardCondition *//* * inherited from DDS_Condition *//* DDS_boolean * DDS_GuardCondition_get_trigger_value * (DDS_GuardCondition _this); *//* * implemented API operations

145API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

*/DDS_GuardCondition DDS_GuardCondition__alloc (void);DDS_ReturnCode_t DDS_GuardCondition_set_trigger_value (DDS_GuardCondition _this, const DDS_boolean value);

The following sections describe the usage of all DDS_GuardConditionoperations. The inherited operation is listed but not fully described since it is not implementedin this class. The full description of this operation is given in the class from which itis inherited. This is described in their respective paragraph.

3.1.8.1 DDS_GuardCondition__alloc

Synopsis#include <dds_dcps.h>DDS_GuardCondition DDS_GuardCondition__alloc (void);

DescriptionThis operation creates a new DDS_GuardCondition.

Parameters<none>

Return ValueDDS_GuardCondition - Return value is the handle to the newly-created

DDS_GuardCondition. In case of an error, a DDS_OBJECT_NIL pointer isreturned.

Detailed DescriptionThis operation creates a new DDS_GuardCondition. The DDS_GuardConditionmust be created using this operation. In other words, the application is not allowedto declare an object of type DDS_GuardCondition. When the application wants torelease the DDS_GuardCondition it must be released using DDS_free.I n c a s e t h e r e a r e i n s u ff i c i e n t r e s o u r c e s a v a i l a b l e t o a l l o c a t e t h eDDS_GuardCondition, a DDS_OBJECT_NIL pointer is returned instead.

146API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

3.1.8.2 DDS_GuardCondition_get_trigger_value (inherited)This operation is inherited and therefore not described here. See the classDDS_Condition for further explanation.

Synopsis#include <dds_dcps.h>DDS_boolean DDS_GuardCondition_get_trigger_value (DDS_GuardCondition _this);

3.1.8.3 DDS_GuardCondition_set_trigger_value

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_GuardCondition_set_trigger_value (DDS_GuardCondition _this, const DDS_boolean value);

DescriptionThis operation sets the trigger_value of the DDS_GuardCondition.

Parametersin DDS_GuardCondition _this - the DDS_GuardCondition object on

which the operation is operated.in const DDS_boolean value - the boolean value to which the

DDS_GuardCondition is set.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK , DDS_RETCODE_ERROR o r DDS_RETCODE_ILLEGAL_OPERATION.

Detailed DescriptionA DDS_GuardCondition object is a specific DDS_Condition whichtrigger_value is completely under the control of the application. This operationmust be used by the application to manually wake-up a DDS_WaitSet. Thisoperation sets the trigger_value of the DDS_GuardCondition to the parametervalue . T h e DDS_GuardCondition i s d i r e c t l y c r e a t e d u s i n g t h eDDS_GuardCondition constructor. When a DDS_GuardCondition is initiallycreated, the trigger_value is FALSE.

147API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the specified trigger_value has successfully been applied• DDS_RETCODE_ERROR - an internal error has occurred• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object

3.1.9 Class DDS_StatusConditionDDS_Entity o b j e c t s t h a t h a v e s t a tu s a t t r i b u t e s a l s o h a v e aDDS_StatusCondition , access is provided to the application by theDDS_<Entity>_get_statuscondition operation.The communication statuses whose changes can be communicated to the applicationdepend on the DDS_Entity. The following table shows the relevant statuses foreach DDS_Entity.

The trigger_value of the DDS_StatusCondition depends on thecommunication statuses of that DDS_Entity (e.g., missed deadline) and alsodepends on the value of the DDS_StatusCondition a t t r ibute mask(enabled_statuses mask). A DDS_StatusCondition can be attached to aDDS_WaitSet in order to a l low an appl icat ion to suspend unt i l thetrigger_value has become TRUE.

Table 17: Status Per DDS_Entity

DDS_Entity Status NameDDS_Topic DDS_INCONSISTENT_TOPIC_STATUS

DDS_ALL_DATA_DISPOSED_TOPIC_STATUS

DDS_Subscriber DDS_DATA_ON_READERS_STATUS

DDS_DataReader DDS_SAMPLE_REJECTED_STATUS

DDS_LIVELINESS_CHANGED_STATUS

DDS_REQUESTED_DEADLINE_MISSED_STATUS

DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS

DDS_DATA_AVAILABLE_STATUS

DDS_SAMPLE_LOST_STATUS

DDS_SUBSCRIPTION_MATCHED_STATUS

DDS_DataWriter DDS_LIVELINESS_LOST_STATUS

DDS_OFFERED_DEADLINE_MISSED_STATUS

DDS_OFFERED_INCOMPATIBLE_QOS_STATUS

DDS_PUBLICATION_MATCHED_STATUS

148API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

The trigger_value of a DDS_StatusCondition will be TRUE if one of theenabled StatusChangedFlags is set. That is, trigger_value==FALSE only ifall the values of the StatusChangedFlags are FALSE.The sensitivity of the DDS_StatusCondition to a particular communicationstatus is controlled by the list of enabled_statuses set on the condition bymeans of the DDS_StatusCondition_set_enabled_statuses operation.W h e n t h e enabled_statuses a r e n o t c h a ng e d b y t h eDDS_StatusCondition_set_enabled_statuses operation, all statuses areenabled by default.The interface description of this class is as follows:

/* * interface DDS_StatusCondition *//* * inherited from DDS_Condition *//* DDS_boolean * DDS_StatusCondition_get_trigger_value * (DDS_StatusCondition _this); *//* * implemented API operations */

DDS_StatusMask DDS_StatusCondition_get_enabled_statuses (DDS_StatusCondition _this);DDS_ReturnCode_t DDS_StatusCondition_set_enabled_statuses (DDS_StatusCondition _this, const DDS_StatusMask mask);DDS_Entity DDS_StatusCondition_get_entity (DDS_StatusCondition _this);

The next paragraphs describe the usage of all DDS_StatusCondition operations.The inherited operations are listed but not fully described because they are notimplemented in this class. The full description of these operations is given in theclasses from which they are inherited.

3.1.9.1 DDS_StatusCondition_get_enabled_statuses

Synopsis#include <dds_dcps.h>DDS_StatusMask DDS_StatusCondition_get_enabled_statuses (DDS_StatusCondition _this);

149API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

DescriptionThis operation returns the list of enabled communication statuses of theDDS_StatusCondition.

Parametersin DDS_StatusCondition _this - the DDS_StatusCondition object on

which the operation is operated.

Return ValueDDS_StatusMask - Result is a bit-mask in which each bit shows which status is

taken into account for the DDS_StatusCondition.

Detailed DescriptionThe trigger_value of the DDS_StatusCondition depends on thecommunication status of that DDS_Entity (e.g., missed deadline, loss ofinformation, etc.), ‘filtered’ by the set of enabled_statuses on theDDS_StatusCondition.This operation returns the list of communication statuses that are taken into accountto determine the trigger_value of the DDS_StatusCondition. This operationr e t u r n s t h e s t a tu s e s t h a t w e r e e x p l i c i t l y s e t on t he l a s t c a l l t oDDS_StatusCondition_set_enabled_statuses o r, i fDDS_StatusCondition_set_enabled_statuses was never called, the defaultlist.The result value is a bit-mask in which each bit shows which status is taken intoaccount for the DDS_StatusCondition. The relevant bits represents one of thefollowing statuses:

DDS_INCONSISTENT_TOPIC_STATUSDDS_ALL_DATA_DISPOSED_TOPIC_STATUSDDS_OFFERED_DEADLINE_MISSED_STATUSDDS_REQUESTED_DEADLINE_MISSED_STATUSDDS_OFFERED_INCOMPATIBLE_QOS_STATUSDDS_REQUESTED_INCOMPATIBLE_QOS_STATUSDDS_SAMPLE_LOST_STATUSDDS_SAMPLE_REJECTED_STATUSDDS_DATA_ON_READERS_STATUSDDS_DATA_AVAILABLE_STATUSDDS_LIVELINESS_LOST_STATUSDDS_LIVELINESS_CHANGED_STATUSDDS_PUBLICATION_MATCHED_STATUSDDS_SUBSCRIPTION_MATCHED_STATUS.

150API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

Each status bit is declared as a constant and can be used in an AND operation tocheck the status bit against the result of type DDS_StatusMask. Not all statuses arerelevant to all DDS_Entity objects. See the respective Listener objects for eachDDS_Entity for more information.

3.1.9.2 DDS_StatusCondition_get_entity

Synopsis#include <dds_dcps.h>DDS_Entity DDS_StatusCondition_get_entity (DDS_StatusCondition _this);

DescriptionT h i s o p e r a t i o n r e t u r n s t h e DDS_Entity a s soc i a t ed w i th t heDDS_StatusCondition or the DDS_OBJECT_NIL pointer.

Parametersin DDS_StatusCondition _this - the DDS_StatusCondition object on

which the operation is operated.

Return ValueDDS_Entity - a p o i n t e r t o t h e DDS_Entity a s s o c i a t e d w i t h t h e

DDS_StatusCondition or the DDS_OBJECT_NIL pointer.

Detailed DescriptionT h i s o p e r a t i o n r e t u r n s t h e DDS_Entity a s soc i a t ed w i th t heDDS_StatusCondition. Note that there is exactly one DDS_Entity associatedwith each DDS_StatusCondition. When the DDS_Entity was already deleted(there is no associated DDS_Entity any more), the DDS_OBJECT_NIL pointer isreturned.

3.1.9.3 DDS_StatusCondition_get_trigger_value (inherited)This operation is inherited and therefore not described here. See the classDDS_Condition for further explanation.

Synopsis#include <dds_dcps.h>DDS_boolean DDS_StatusCondition_get_trigger_value (DDS_StatusCondition _this);

151API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

3.1.9.4 DDS_StatusCondition_set_enabled_statuses

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_StatusCondition_set_enabled_statuses (DDS_StatusCondition _this, const DDS_StatusMask mask);

DescriptionThis operation sets the list of communication statuses that are taken into account todetermine the trigger_value of the DDS_StatusCondition.

Parametersin DDS_StatusCondition _this - the DDS_StatusCondition object on

which the operation is operated.in const DDS_StatusMask mask - a bit-mask in which each bit sets the status

which is taken into account for the DDS_StatusCondition.

Return ValueDDS_ReturnCode_t - Poss ib le r e tu rn codes o f the ope ra t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION or DDS_RETCODE_ALREADY_DELETED.

Detailed DescriptionThe trigger_value of the DDS_StatusCondition depends on thecommunication status of that DDS_Entity (e.g., missed deadline, loss ofinformation, etc.), ‘filtered’ by the set of enabled_statuses on theDDS_StatusCondition.This operation sets the list of communication statuses that are taken into account todetermine the trigger_value of the DDS_StatusCondition. This operationmay change the trigger_value of the DDS_StatusCondition.DDS_WaitSet objects behaviour depend on the changes of the trigger_value oftheir attached DDS_Conditions. Therefore, any DDS_WaitSet to which theDDS_StatusCondition is attached is potentially affected by this operation.If this function is not invoked, the default list of enabled_statuses includes allthe statuses.The parameter mask is a bit-mask in which each bit shows which status is taken intoaccount for the DDS_StatusCondition. The relevant bits represents one of thefollowing statuses:

152API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

DDS_INCONSISTENT_TOPIC_STATUSDDS_ALL_DATA_DISPOSED_TOPIC_STATUSDDS_OFFERED_DEADLINE_MISSED_STATUSDDS_REQUESTED_DEADLINE_MISSED_STATUSDDS_OFFERED_INCOMPATIBLE_QOS_STATUSDDS_REQUESTED_INCOMPATIBLE_QOS_STATUSDDS_SAMPLE_LOST_STATUSDDS_SAMPLE_REJECTED_STATUSDDS_DATA_ON_READERS_STATUSDDS_DATA_AVAILABLE_STATUSDDS_LIVELINESS_LOST_STATUSDDS_LIVELINESS_CHANGED_STATUSDDS_PUBLICATION_MATCHED_STATUSDDS_SUBSCRIPTION_MATCHED_STATUS

Each status bit is declared as a constant and can be used in an OR operation to setthe status bit in the parameter mask of type DDS_StatusMask. Not all statuses arerelevant to all DDS_Entity objects. See the respective Listener objects for eachDDS_Entity for more information.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the list of communication statuses is set.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_StatusCondition has already

been deleted.

3.1.10 Class DDS_ErrorInfoThe DDS_ErrorInfo mechanism is an OpenSplice-specific extension to theOMG-DDS standard, that can help DDS users to get a more finegrained overview ofthe context of an error. The DDS specification only mandates that functions return aDDS_ReturnCode_t value as a broad categorization of potential types of problems(there are 12 possible DDS_ReturnCode_t values, of which 11 indicate some kindof error), but factory operations do not even have this mechanism at their disposalsince they return the object they were requested to create.The DDS_ErrorInfo was added to OpenSplice for the following reasons:• It can provide context for errors that occur in factory operations (e.g. whencreate_topic returns NULL).

153API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

• It can provide a DDS_ErrorCode_t value, that represents a much morefine-grained error categorization than the DDS_ReturnCode_t (21 categories vs.the 11 categories provided by DDS_ReturnCode_t).

• It can provide an error description that can give a much more dedicatedexplanation of the exact circumstances of the error.

• It can provide the name of the function call/component that caused the error.• It can provide source code location where the error occured (file name + line

number).• It can provide a stacktrace of the thread that ran into the error.The DDS_ErrorInfo obtains its information from the API-level log messagesrecorded by the internal mechanisms of the data distribution service. These aremessages that are, by default, also written to the ospl-info.log file. Theapplication can access this information through an DDS_ErrorInfo object, andtake appropriate action based on the contents of this information. TheDDS_ErrorInfo has no factory and an instance of the class can be created by theapplication by calling its constructor. The interface of this class is as follows:DDS_ErrorInfo DDS_ErrorInfo__alloc (void);

DDS_ReturnCode_t DDS_ErrorInfo_update (DDS_ErrorInfo _this);

DDS_ReturnCode_t DDS_ErrorInfo_get_code (DDS_ErrorInfo _this, DDS_ErrorCode_t *code);

DDS_ReturnCode_t DDS_ErrorInfo_get_message (DDS_ErrorInfo _this, DDS_string *message);

DDS_ReturnCode_t DDS_ErrorInfo_get_location (DDS_ErrorInfo _this, DDS_string *location);

DDS_ReturnCode_t DDS_ErrorInfo_get_source_line (DDS_ErrorInfo _this, DDS_string* source_line);

154API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

DDS_ReturnCode_t DDS_ErrorInfo_get_stack_trace (DDS_ErrorInfo _this, DDS_string* stack_trace);

The following sections describe the usage of all DDS_ErrorInfo operations.

3.1.10.1 DDS_ErrorInfo__alloc

Synopsis#include <dds_dcps.h>DDS_ErrorInfo DDS_ErrorInfo__alloc (void);

DescriptionThis operation creates a new DDS_ErrorInfo.

Parameters<none>

Return ValueDDS_ErrorInfo - handle to the newly-created DDS_ErrorInfo. In case of an

error, a DDS_OBJECT_NIL pointer is returned.

Detailed DescriptionThis operation creates a new DDS_ErrorInfo. The DDS_ErrorInfo must becreated using this operation. In other words, the application is not allowed to declarean object of type DDS_ErrorInfo. When the application wants to release theDDS_ErrorInfo it must be released using DDS_free.If there are insufficient resources available to allocate the DDS_ErrorInfo, aDDS_OBJECT_NIL pointer is returned instead.

3.1.10.2 DDS_ErrorInfo_update

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_ErrorInfo_update (DDS_ErrorInfo _this);

155API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

DescriptionThis operation updates the DDS_ErrorInfo object with the latest availableinformation.

Parametersin DDS_ErrorInfo _this - the DDS_ErrorInfo object on which the operation

is operated.

Return ValueDDS_ReturnCode_t - Poss ib le re turn codes of the opera t ion are :

DDS_RETCODE_OK, DDS_RETCODE_NO_DATA.

Detailed DescriptionThis operation requests the latest error information from the data distribution serviceand stores it in the DDS_ErrorInfo object. The error information remainsavailable in the DDS_ErrorInfo object until a new error occurs and the updateoperation is explicitly invoked on the DDS_ErrorInfo object. If the information issuccessfully updated, DDS_RETCODE_OK is returned. If no information is availablebecause no error has occurred yet, DDS_RETCODE_NO_DATA is returned.

3.1.10.3 DDS_ErrorInfo_get_code

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_ErrorInfo_get_code (DDS_ErrorInfo _this, DDS_ErrorCode_t* code);

NOTE: This operation is not yet consistently implemented everywhere: variouskinds of errors are still categorized as ‘UNDEFINED’.

DescriptionThis operation retrieves the error code of the last error message.

Parametersin DDS_ErrorInfo _this - the DDS_ErrorInfo object on which the operation

is operated.inout ErrorCode_t* code - The DDS_ErrorCode_t struct in which the error

code will be stored.

156API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_NO_DATA.

Detailed DescriptionThis operation stores the error code of the latest error in the providedDDS_ErrorCode_t struct. The DDS_ErrorCode_t type is an OpenSplice-specificequivalent to the DDS_ReturnCode_t type that is mandated by the OMG-DDSstandard, but the DDS_ErrorCode_t type has a more fine-grained errorcategorization which uses 21 categories instead of the 11 provided by theDDS_ReturnCode_t type.Table 18: below contains a list of all supported DDS_ErrorInfo values and theirmeaning.

Table 18: All DDS_ErrorInfo values

Label Value Meaning.DDS_ERRORCODE_UNDEFINED 0 Error has not (yet) been categorized.DDS_ERRORCODE_ERROR 1 Unexpected error.DDS_ERRORCODE_OUT_OF_RESOURCES 2 Not enough resources to complete the

operation.DDS_ERRORCODE_CREATION_KERNEL_ ENTITY_FAILED

3 The kernel was not able to create the entity.Probably there is not enough sharedmemory available.

DDS_ERRORCODE_INVALID_VALUE 4 A value is passed that is outside its validbounds.

DDS_ERRORCODE_INVALID_DURATION 5 A Duration is passed that is outside its validbounds or that has not been normalizedproperly.

DDS_DDS_ERRORCODE_INVALID_TIME 6 A Time is passed that is outside its validbounds or that has not been normalizedproperly.

DDS_ERRORCODE_ENTITY_INUSE 7 Attempted to delete an entity that is still inuse.

DDS_ERRORCODE_CONTAINS_ENTITIES 8 Attempted to delete a factory that stillcontains entities.

DDS_ERRORCODE_ENTITY_UNKNOWN 9 A pointer to an unknown entity has beenpassed.

DDS_ERRORCODE_HANDLE_NOT_REGISTERED 10 A handle has been passed that is no longerin use.

157API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

3.1.10.4 DDS_ErrorInfo_get_message

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_ErrorInfo_get_message (DDS_ErrorInfo _this, DDS_string* message);

DescriptionThis operation retrieves the description of the latest error.

DDS_ERRORCODE_HANDLE_NOT_MATCH 11 A handle has been passed to an entity towhich it does not belong.

DDS_ERRORCODE_HANDLE_INVALID 12 An unknown handle has been passed.DDS_ERRORCODE_INVALID_SEQUENCE 13 A sequence has been passed that has

inconsistent variables (e.g. length >maximum, buffer equals NULL whilemaximum > 0, etc.)

DDS_ERRORCODE_UNSUPPORTED_VALUE 14 A value has been passed that is not (yet)supported.

DDS_ERRORCODE_INCONSISTENT_VALUE 15 A value has been passed that is inconsistent DDS_ERRORCODE_IMMUTABLE_QOS_POLICY 16 Attempted to modify a QosPolicy that is

immutable.DDS_ERRORCODE_INCONSISTENT_QOS 17 Attempted to set QosPolicy values that are

mutually inconsistent.DDS_ERRORCODE_UNSUPPORTED_QOS_POLICY 18 Attempted to pass a QosPolicy setting that

is not (yet) supported.DDS_ERRORCODE_CONTAINS_CONDITIONS 19 Attempted to delete a WaitSet that still has

Conditions attached to it.DDS_ERRORCODE_CONTAINS_LOANS 20 A t t e m p t e d t o d e l e t e a

DataReader/DataView that has unreturnedloans.

DDS_ERRORCODE_INCONSISTENT_TOPIC 21 At tempted to c rea t e a t op ic tha t i sinconsistent with existing topic definitions.

Table 18: All DDS_ErrorInfo values (continued)

Label Value Meaning.

158API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

Parametersin DDS_ErrorInfo _this - the DDS_ErrorInfo object on which the operation

is operated.inout DDS_string* message - Reference to a string holding the latest

description.

Return ValueDDS_ReturnCode_t - Poss ib le re turn codes of the opera t ion are :

DDS_RETCODE_OK, DDS_RETCODE_NO_DATA.

Detailed DescriptionThis operation stores the description of the latest error in a newly-allocated string. Ifthe pointer supplied by the application through the message parameter alreadycontains a string, it is freed. If no error has occurred, DDS_RETCODE_NO_DATA isreturned and NULL is assigned to the message parameter.

3.1.10.5 DDS_ErrorInfo_get_location

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_ErrorInfo_get_location (DDS_ErrorInfo _this, DDS_string* location);

DescriptionThis operation retrieves the location or context of the latest error.

Parametersin DDS_ErrorInfo _this - the DDS_ErrorInfo object on which the operation

is operated.inout DDS_string* message - Pointer to a string holding the location of the

latest error.

Return ValueDDS_ReturnCode_t - Poss ib le re turn codes of the opera t ion are :

DDS_RETCODE_OK, DDS_RETCODE_NO_DATA.

159API Reference

3 DCPS Classes and Operations 3.1 Infrastructure Module

Detailed DescriptionThis operation stores the context or location of the latest error in a newly-allocatedstring. The string may contain the name of an operation or component of the datadistribution service in which the error occurred, or other descriptive information onthe location of the error. If the pointer supplied by the application through thelocation parameter already contains a string, it is freed. If no error has occurred,DDS_RETCODE_NO_DATA is returned and NULL is assigned to the locationparameter.

3.1.10.6 DDS_ErrorInfo_get_source_line

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_ErrorInfo_get_source_line (DDS_ErrorInfo _this, DDS_string* source_line);

DescriptionThis operation retrieves the location within the sourcecode of the latest error.

Parametersin DDS_ErrorInfo _this - the DDS_ErrorInfo object on which the operation

is operated.inout DDS_string* source_line - Pointer to a string holding the sourcecode

information of the latest error.

Return ValueDDS_ReturnCode_t - Poss ib le re turn codes of the opera t ion are :

DDS_RETCODE_OK, DDS_RETCODE_NO_DATA.

Detailed DescriptionThis operation stores the name and line number of the source file in which the latesterror occurred, seperated by a colon, in a newly-allocated string. If the pointersupplied by the application through the source_line parameter already contains astring, it is freed. If no error has occurred, DDS_RETCODE_NO_DATA is returned andNULL is assigned to the source_line parameter.

3.1.10.7 DDS_ErrorInfo_get_stack_trace

Synopsis#include <dds_dcps.h>

160API Reference

3 DCPS Classes and Operations 3.2 Domain Module

DDS_ReturnCode_t DDS_ErrorInfoget_stack_trace (DDS_ErrorInfo _this, DDS_string* stack_trace);

NOTE: This operation is not yet implemented. It is scheduled for a future release.

3.2 Domain Module

Figure 15: DCPS Domain Module’s Class ModelThis module contains the following classes:

DDS_DomainParticipantDDS_DomainParticipantFactoryDDS_DomainParticipantListener (interface)DDS_Domain (not depicted)

3.2.1 Class DDS_DomainParticipantAll the DCPS DDS_Entity objects are attached to a DDS_DomainParticipant.A DDS_DomainParticipant represents the local membership of the applicationin a Domain.

SubscriberListener(from Subscription Module)

<<Interface>>

TopicListener

on_inconsistent_topic()

<<Interface>>

PublisherListener(from Publication Module)

<<Interface>> Entity(from Infrastructure Module)

Publisher(from Publication Module)

Subscriber(from Subscription Module)

ContentFilteredTopic(from Topic-Definition Module)

MultiTopic(from Topic-Definition Module)DomainParticipantFactory

create_participant()

delete_participant()get_default_participant_qos()get_instance()lookup_participant()set_default_participant_qos()

DomainEntity(from Infrastructure Module)

QosPolicy(from Infrastructure Module)

**

default_participant_qos

DomainParticipantListener

DomainParticipant

assert_liveliness()contains_entity()create_contentfilteredtopic()create_multitopic()create_publisher()create_subscriber()create_topic()delete_contained_entities()delete_contentfilteredtopic()delete_multitopic()delete_publisher()delete_subscriber()delete_topic()find_topic()get_builtin_subscriber()get_current_time()get_default_publisher_qos()get_default_subscriber_qos()get_default_topic_qos()get_domain_id()get_listener()get_qos()ignore_participant()ignore_publication()ignore_subscription()ignore_topic()lookup_topic_description()set_default_publisher_qos()set_default_subscriber_qos()set_default_topic_qos()set_listener()set_qos()

**

11

**

qos<<implicit>>

**default_publisher_qos

** default_topic_qos**

default_subscriber_qos

0..10..1

<<implicit>>

Topic(from Topic-Definition Module)

TopicDescription(from Topic-Definition Module)

**

<<implicit>>

<<create>>

<<create>>

<<create>>

<<create>>

<<create>>

<<create>>

delete_contained_entities()

161API Reference

3 DCPS Classes and Operations 3.2 Domain Module

A Domain is a distributed concept that links all the applications that must be able tocommunicate with each other. It represents a communication plane: only theDDS_Publishers and the DDS_Subscribers attached to the same Domain caninteract.This class implements several functions:• It acts as a container for all other DDS_Entity objects• It acts as a factory for the DDS_Publisher, DDS_Subscriber, DDS_Topic,DDS_ContentFilteredTopic and DDS_MultiTopic objects

• It provides access to the built-in DDS_Topic objects• It provides information about DDS_Topic objects• It isolates applications within the same Domain (sharing the same domainId)

from other applications in a different Domain on the same set of computers. Inthis way, several independent distributed applications can coexist in the samephysical network without interfering, or even being aware of each other

• It provides administration services in the Domain, offering operations, whichallow the application to ignore locally any information about a givenParticipant, Publication, Subscription or Topic.

The interface description of this class is as follows:/* * interface DDS_DomainParticipant *//* * inherited from class DDS_Entity *//* DDS_StatusCondition * DDS_DomainParticipant_get_statuscondition * (DDS_DomainParticipant _this); *//* DDS_StatusMask * DDS_DomainParticipant_get_status_changes * (DDS_DomainParticipant _this); *//* DDS_ReturnCode_t * DDS_DomainParticipant_enable * (DDS_DomainParticipant _this); *//* * implemented API operations */

DDS_Publisher DDS_DomainParticipant_create_publisher (DDS_DomainParticipant _this, const DDS_PublisherQos *qos,

162API Reference

3 DCPS Classes and Operations 3.2 Domain Module

const struct DDS_PublisherListener *a_listener, const DDS_StatusMask mask);

DDS_ReturnCode_t DDS_DomainParticipant_delete_publisher (DDS_DomainParticipant _this, const DDS_Publisher p);DDS_Subscriber DDS_DomainParticipant_create_subscriber (DDS_DomainParticipant _this, const DDS_SubscriberQos *qos,

const struct DDS_SubscriberListener *a_listener, const DDS_StatusMask mask);

DDS_ReturnCode_t DDS_DomainParticipant_delete_subscriber (DDS_DomainParticipant _this, const DDS_Subscriber s);DDS_Subscriber DDS_DomainParticipant_get_builtin_subscriber (DDS_DomainParticipant _this);DDS_Topic DDS_DomainParticipant_create_topic (DDS_DomainParticipant _this, const DDS_char *topic_name,

const DDS_char *type_name, const DDS_TopicQos *qos, const struct DDS_TopicListener *a_listener, const DDS_StatusMask mask);

DDS_ReturnCode_t DDS_DomainParticipant_delete_topic (DDS_DomainParticipant _this, const DDS_Topic a_topic);DDS_Topic DDS_DomainParticipant_find_topic (DDS_DomainParticipant _this, const DDS_char *topic_name, const DDS_Duration_t *timeout);DDS_TopicDescription DDS_DomainParticipant_lookup_topicdescription (DDS_DomainParticipant _this, const DDS_char *name);DDS_ContentFilteredTopic DDS_DomainParticipant_create_contentfilteredtopic (DDS_DomainParticipant _this, const DDS_char *name, const DDS_Topic related_topic, const DDS_char *filter_expression, const DDS_StringSeq *expression_parameters);DDS_ReturnCode_t DDS_DomainParticipant_delete_contentfilteredtopic (DDS_DomainParticipant _this,

163API Reference

3 DCPS Classes and Operations 3.2 Domain Module

const DDS_ContentFilteredTopic a_contentfilteredtopic);DDS_MultiTopic DDS_DomainParticipant_create_multitopic (DDS_DomainParticipant _this, const DDS_char *name, const DDS_char *type_name, const DDS_char *subscription_expression, const DDS_StringSeq *expression_parameters);DDS_ReturnCode_t DDS_DomainParticipant_delete_multitopic (DDS_DomainParticipant _this, const DDS_MultiTopic a_multitopic);DDS_ReturnCode_t DDS_DomainParticipant_delete_contained_entities (DDS_DomainParticipant _this);DDS_ReturnCode_t DDS_DomainParticipant_set_qos (DDS_DomainParticipant _this, const DDS_DomainParticipantQos *qos);DDS_ReturnCode_t DDS_DomainParticipant_get_qos (DDS_DomainParticipant _this, DDS_DomainParticipantQos *qos);DDS_ReturnCode_t DDS_DomainParticipant_set_listener (DDS_DomainParticipant _this, const struct DDS_DomainParticipantListener *a_listener, const DDS_StatusMask mask);struct DDS_DomainParticipantListener DDS_DomainParticipant_get_listener (DDS_DomainParticipant _this);DDS_ReturnCode_t DDS_DomainParticipant_ignore_participant (DDS_DomainParticipant _this, const DDS_InstanceHandle_t handle);DDS_ReturnCode_t DDS_DomainParticipant_ignore_topic (DDS_DomainParticipant _this, const DDS_InstanceHandle_t handle);DDS_ReturnCode_t DDS_DomainParticipant_ignore_publication (DDS_DomainParticipant _this, const DDS_InstanceHandle_t handle);DDS_ReturnCode_t DDS_DomainParticipant_ignore_subscription (DDS_DomainParticipant _this, const DDS_InstanceHandle_t handle);DomainId_t DDS_DomainParticipant_get_domain_id

164API Reference

3 DCPS Classes and Operations 3.2 Domain Module

(DDS_DomainParticipant _this);DDS_ReturnCode_t DDS_DomainParticipant_get_discovered_participants (DDS_DomainParticipant _this, DDS_InstanceHandleSeq *participant_handles);DDS_ReturnCode_t DDS_DomainParticipant_get_discovered_participant_data (DDS_DomainParticipant _this, DDS_ParticipantBuiltinTopicData *participant_data, DDS_InstanceHandle_t handle);DDS_ReturnCode_t DDS_DomainParticipant_get_discovered_topics (DDS_DomainParticipant _this, DDS_InstanceHandleSeq *topic_handles);DDS_ReturnCode_t DDS_DomainParticipant_get_discovered_topic_data (DDS_DomainParticipant _this, DDS_TopicBuiltinTopicData *topic_data, DDS_InstanceHandle_t handle);DDS_ReturnCode_t DDS_DomainParticipant_assert_liveliness (DDS_DomainParticipant _this);DDS_ReturnCode_t DDS_DomainParticipant_set_default_publisher_qos (DDS_DomainParticipant _this, const DDS_PublisherQos *qos);DDS_ReturnCode_t DDS_DomainParticipant_get_default_publisher_qos (DDS_DomainParticipant _this, DDS_PublisherQos *qos);DDS_ReturnCode_t DDS_DomainParticipant_set_default_subscriber_qos (DDS_DomainParticipant _this, const DDS_SubscriberQos *qos);DDS_ReturnCode_t DDS_DomainParticipant_get_default_subscriber_qos (DDS_DomainParticipant _this, DDS_SubscriberQos *qos);DDS_ReturnCode_t DDS_DomainParticipant_set_default_topic_qos (DDS_DomainParticipant _this, const DDS_TopicQos *qos);DDS_ReturnCode_t DDS_DomainParticipant_get_default_topic_qos (DDS_DomainParticipant _this, DDS_TopicQos *qos);DDS_boolean contains_entity (DDS_InstanceHandle_t a_handle);DDS_ReturnCode_t

165API Reference

3 DCPS Classes and Operations 3.2 Domain Module

get_current_time (DDS_Time_t *current_time);

The following sections describe the usage of all DDS_DomainParticipantoperations. The inherited operations are listed but not fully described because theyare not implemented in this class. The full description of these operations is given inthe classes from which they are inherited.

3.2.1.1 DDS_DomainParticipant_assert_liveliness

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_assert_liveliness (DDS_DomainParticipant _this);

DescriptionThis operation asserts the liveliness for the DDS_DomainParticipant.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant object

on which the operation is operated.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_ALREADY_DELETED , DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_NOT_ENABLED.

Detailed DescriptionT h i s o p e r a t i o n w i l l m a n u a l l y a s s e r t t h e l i v e l i n e s s f o r t h eDDS_DomainParticipant. This way, the Data Distribution Service is informedthat the DDS_DomainParticipant is still alive. This operation only needs to beused when the DDS_DomainParticipant contains DDS_DataWriters with theDDS_LivelinessQosPolicy s e t t oDDS_MANUAL_BY_PARTICIPANT_LIVELINESS_QOS, and it will only affect theliveliness of those DDS_DataWriters.Writing data via the DDS_DataWriter_write operation of a DDS_DataWriterw i l l a s s e r t t h e l i v e l i n e s s o n t h e DDS_DataWriter i t s e l f a n d i t sDDS_DomainParticipant. DDS_DomainParticipant_assert_livelinesssubsequently is only needed when data is not written regularly.The liveliness should be asserted by the application, depending on theDDS_LivelinessQosPolicy.

166API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the liveliness of this DDS_DomainParticipant has

successfully been asserted.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_DomainParticipant has

already been deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_NOT_ENABLED - the DDS_DomainParticipant is not enabled.

3.2.1.2 DDS_DomainParticipant_contains_entity

Synopsis#include <dds_dcps.h>DDS_boolean contains_entity (DDS_DomainParticipant _this,

DDS_InstanceHandle_t a_handle);

DescriptionThis operation checks whether or not the given Entity represented by a_handleis created by the DDS_DomainParticipant or any of its contained entities.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant object

on which the operation is operated.in DDS_InstanceHandle_t a_handle - represents a DDS_Entity in the Data

Distribution System.

Return ValueDDS_boolean - Return value is TRUE if a_handle represents a DDS_Entity

that is created by the DDS_DomainParticipant or any of its containedDDS_Entites. Otherwise the return value is FALSE.

167API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Detailed DescriptionThis operation checks whether or not the given Entity represented by a_handleis created by the DDS_DomainParticipant itself (DDS_TopicDescription,DDS_Publisher or DDS_Subscriber) or created by any of its contained entities(DDS_DataReader, DDS_ReadCondition , DDS_QueryCondition ,DDS_DataWriter, etc.).Return value is TRUE if a_handle represents a DDS_Entity that is created by theDDS_DomainParticipant or any of its contained DDS_Entites. Otherwise thereturn value is FALSE.

3.2.1.3 DDS_DomainParticipant_create_contentfilteredtopic

Synopsis#include <dds_dcps.h>DDS_ContentFilteredTopic DDS_DomainParticipant_create_contentfilteredtopic (DDS_DomainParticipant _this, const DDS_char *name, const DDS_Topic related_topic, const DDS_char *filter_expression, const DDS_StringSeq *expression_parameters);

DescriptionT h i s o p e r a t i o n c r e a t e s a DDS_ContentFilteredTopic f o r aDDS_DomainParticipant in order to allow DDS_DataReaders to subscribe to asubset of the topic content.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant object

on which the operation is operated.in const DDS_char *name - con t a in s t he na me o f t he

DDS_ContentFilteredTopic.in const DDS_Topic related_topic - the handle to the base DDS_Topic

on which the filtering will be applied. Therefore, a filtered topic is based on anexisting DDS_Topic.

in const DDS_char *filter_expression - holds the SQL expression(subset of SQL), which defines the filtering.

in const DDS_StringSeq *expression_parameters - the handle to asequence of strings with the parameter value used in the SQL expression (i.e.,the number of %n tokens in the expression). The number of values inexpression_parameters must be equal or greater than the highest

168API Reference

3 DCPS Classes and Operations 3.2 Domain Module

referenced %n token in the filter_expression (e.g. if %1 and %8 are used asparameter in the filter_expression, the expression_parametersshould at least contain n+1 = 9 values).

Return ValueDDS_ContentFilteredTopic - Return value is the handle to the newly-created

DDS_ContentFilteredTopic. In case of an error, a nil pointer is returned.

Detailed DescriptionT h i s o p e r a t i o n c r e a t e s a DDS_ContentFilteredTopic f o r aDDS_DomainParticipant in order to allow DDS_DataReaders to subscribe to asubset of the topic content. The base topic, which is being filtered is defined by theparameter related_topic. The resulting DDS_ContentFilteredTopic onlyrelates to the samples published under the related_topic, which have beenfiltered according to their content. The resulting DDS_ContentFilteredTopiconly exists at the DDS_DataReader side and will never be published. The samplesof the related_topic are filtered according to the SQL expression, which is asubset of SQL as defined in the parameter filter_expression (see Appendix H,DCPS Queries and Filters). The filter_expression may also contain parameters, which appear as %ntokens in the expression which must be set by the sequence of strings defined by thepa ra me te r expression_parameters . T h e n u m b e r o f v a l u e s i nexpression_parameters must be equal or greater than the highest referenced%n token in the filter_expression (e.g. if %1 and %8 are used as parameter inthe filter_expression, the expression_parameters should at least contain n+1 =9 values).The filter_expression is a string that specifies the criteria to select the datasamples of interest. In other words, it identifies the selection of data from theassociated DDS_Topics. It is an SQL expression where the WHERE clause gives thecontent filter.

3.2.1.4 DDS_DomainParticipant_create_multitopic

Synopsis#include <dds_dcps.h>DDS_MultiTopic DDS_DomainParticipant_create_multitopic (DDS_DomainParticipant _this, const DDS_char *name, const DDS_char *type_name, const DDS_char *subscription_expression, const DDS_StringSeq *expression_parameters);

169API Reference

3 DCPS Classes and Operations 3.2 Domain Module

NOTE: This operation is not yet implemented. It is scheduled for a future release.

DescriptionThis operation creates a DDS_MultiTopic for a DDS_DomainParticipant inorder to allow DDS_DataReaders to subscribe to a filtered/re-arrangedcombination and/or subset of the content of several topics.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant object

on which the operation is operated.in const DDS_char *name - contains the name of the DDS_MultiTopic.in const DDS_char *type_name - contains the name of the type of the

DDS_MultiTopic. This type_name must have been registered usingDDS_TypeSupport_register_type prior to calling this operation.

in const DDS_char *subscription_expression - the SQL expression(subset of SQL), which defines the selection, filtering, combining andre-arranging of the sample data.

in const DDS_StringSeq *expression_parameters - the handle to asequence of strings with the parameter value used in the SQL expression (i.e.,the number of %n tokens in the expression). The number of values inexpression_parameters must be equal or greater than the highestreferenced %n token in the subscription_expression (e.g. if %1 and %8are used as paramete r in the subscription_expression , theexpression_parameters should at least contain n+1 = 9 values).

Return ValueDDS_MultiTopic - Return value is the handle to the newly-created

DDS_MultiTopic. In case of an error, a nil pointer is returned.

Detailed DescriptionThis operation creates a DDS_MultiTopic for a DDS_DomainParticipant inorder to allow DDS_DataReaders to subscribe to a filtered/re-arrangedcombination and/or subset of the content of several topics. Before theDDS_MultiTopic can be created, the type_name of the DDS_MultiTopic musthave been registered prior to calling this operation. Registering is done, using theDDS_TypeSupport_register_type operation from DDS_TypeSupport. Thelist of topics and the logic, which defines the selection, filtering, combining andre-arranging of the sample data, is defined by the SQL expression, a subset of SQLdefined in subsciption_expression. The subscription_expression mayalso contain parameters, which appear as %n tokens in the expression. These

170API Reference

3 DCPS Classes and Operations 3.2 Domain Module

parameters are defined in expression_parameters. The number of values inexpression_parameters must be equal or greater than the highest referenced%n token in the subscription_expression (e.g. if %1 and %8 are used asparameter in the subscription_expression, the expression_parametersshould at least contain n+1 = 9 values).The subscription_expression is a string that specifies the criteria to select thedata samples of interest. In other words, it identifies the selection and rearrangementof data from the associated DDS_Topics. It is an SQL expression where theSELECT clause provides the fields to be kept, the FROM part provides the names ofthe DDS_Topics that are searched for those fields, and the WHERE clause gives thecontent filter. The DDS_Topics combined may have different types but they arerestricted in that the type of the fields used for the NATURAL JOIN operation mustbe the same.The DDS_DataReader, which is associated with a DDS_MultiTopic onlyaccesses information which exist locally in the DDS_DataReader, based on theDDS_Topics used in the subscription_expression . The ac tualDDS_MultiTopic will never be produced, only the individual DDS_Topics.

3.2.1.5 DDS_DomainParticipant_create_publisher

Synopsis#include <dds_dcps.h>DDS_Publisher DDS_DomainParticipant_create_publisher (DDS_DomainParticipant _this, const DDS_PublisherQos *qos, const struct DDS_PublisherListener *a_listener, const DDS_StatusMask mask);

DescriptionThis operation creates a DDS_Publisher with the desired QosPolicy settings andif applicable, attaches the optionally specified DDS_PublisherListener to it.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant

object on which the operation is operated.in const DDS_PublisherQos *qos - a collection of QosPolicy settings for

the new DDS_Publisher. In case these settings are not self consistent, noDDS_Publisher is created.

171API Reference

3 DCPS Classes and Operations 3.2 Domain Module

in const struct DDS_PublisherListener *a_listener - a pointer to theDDS_PublisherListener instance which will be attached to the newDDS_Publisher. It is permitted to use DDS_OBJECT_NIL as the value of thelistener: this behaves as a DDS_PublisherListener whose operationsperform no action.

in const DDS_StatusMask mask - a bit-mask in which each bit enables theinvocation of the DDS_PublisherListener for a certain status.

Return ValueDDS_Publisher - Return value is a pointer to the newly-created DDS_Publisher.

In case of an error, the DDS_OBJECT_NIL pointer is returned.

Detailed DescriptionThis operation creates a DDS_Publisher with the desired QosPolicy settings andif applicable, attaches the optionally specified DDS_PublisherListener to it.When the DDS_PublisherListener is not applicable, the DDS_OBJECT_NILpointer must be supplied instead. To delete the DDS_Publisher the operationDDS_DomainParticipant_delete_publisher o r DDS_DomainParticipant_delete_contained_entities must be used.In case the specified QosPolicy settings are not consistent, no DDS_Publisher iscreated and the DDS_OBJECT_NIL pointer is returned. DDS_OBJECT_NIL can alsobe returned when insufficient access rights exist for the partition(s) listed in theprovided QoS structure.

Default QoSThe constant DDS_PUBLISHER_QOS_DEFAULT can be used as parameter qos tocreate a DDS_Publisher with the default DDS_PublisherQos as set in theDDS_DomainParticipant. The effect of using DDS_PUBLISHER_QOS_DEFAULTi s t h e s a m e a s c a l l i n g t h e o p e r a t i o nDDS_DomainParticipant_get_default_publisher_qos and using theresulting DDS_PublisherQos to create the DDS_Publisher.

Communication StatusFor each communication status, the StatusChangedFlag flag is initially set toFALSE. It becomes TRUE whenever that communication status changes. For eachco m m un ica t i on s t a t u s a c t i va t ed i n t he mask , t h e a s soc i a t e dDDS_PublisherListener operation is invoked and the communication status isreset to FALSE, as the listener implicitly accesses the status which is passed as aparameter to that operation. The fact that the status is reset prior to calling thelistener means that if the application calls the get_<status_name>_status frominside the listener it will see the status already reset.

172API Reference

3 DCPS Classes and Operations 3.2 Domain Module

The following statuses are applicable to the DDS_PublisherListener:• DDS_OFFERED_DEADLINE_MISSED_STATUS (propagated)• DDS_OFFERED_INCOMPATIBLE_QOS_STATUS (propagated)• DDS_LIVELINESS_LOST_STATUS (propagated)• DDS_PUBLICATION_MATCHED_STATUS (propagated).Be aware that the DDS_PUBLICATION_MATCHED_STATUS is not applicable whenthe infrastructure does not have the information available to determine connectivity.This is the case when OpenSplice is configured not to maintain discoveryinformation in the Networking Service. (See also the description of theNetworkService/Discovery[@enabled] attribute in section 4.4.1.6.1on page 244 of the Deployment Guide.) In this case the operation will returnDDS_OBJECT_NIL.Status bits are declared as a constant and can be used by the application in an ORoperation to create a tailored mask. The special constant DDS_STATUS_MASK_NONEcan be used to indicate that the created entity should not respond to any of itsavailable statuses. The DDS will therefore attempt to propagate these statuses to itsfactory. The special constant DDS_STATUS_MASK_ANY_V1_2 can be used to selectall applicable statuses specified in the “Data Distribution Service for Real-timeSystems Version 1.2” specification.

Status PropagationThe Data Distribution Service will trigger the most specific and relevant Listener.In other words, in case a communication status is also activated on theDDS_DataWriterListener o f a conta ined DDS_DataWriter, theDDS_DataWriterListener on that contained DDS_DataWriter is invokedinstead of the DDS_PublisherListener. This means that a status change on acontained DDS_DataWriter only invokes the DDS_PublisherListener if thecontained DDS_DataWriter itself does not handle the trigger event generated bythe status change.In case a communica t ion s ta tus i s not ac t iva ted in the mask o f theDDS_PublisherListener, the DDS_DomainParticipantListener of thecontaining DDS_DomainParticipant is invoked (if attached and activated for thestatus that occurred). This allows the application to set a default behaviour in theDDS_DomainParticipantListener o f t h e c o n t a i n i n gDDS_DomainParticipant and a DDS_Publisher specific behaviour whenneeded. In case the DDS_DomainParticipantListener is also not attached orthe communication status is not activated in its mask, the application is not notifiedof the change.

173API Reference

3 DCPS Classes and Operations 3.2 Domain Module

3.2.1.6 DDS_DomainParticipant_create_subscriber

Synopsis#include <dds_dcps.h>DDS_Subscriber DDS_DomainParticipant_create_subscriber (DDS_DomainParticipant _this, const DDS_SubscriberQos *qos, const struct DDS_SubscriberListener *a_listener, const DDS_StatusMask mask);

DescriptionThis operation creates a DDS_Subscriber with the desired QosPolicy settingsand if applicable, attaches the optionally specified DDS_SubscriberListener toit.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant

object on which the operation is operated.in const DDS_SubscriberQos *qos - a collection of QosPolicy settings

for the new DDS_Subscriber. In case these settings are not self consistent, noDDS_Subscriber is created.

in const struct DDS_SubscriberListener *a_listener - a pointer tothe DDS_SubscriberListener instance which will be attached to the newDDS_Subscriber. It is permitted to use DDS_OBJECT_NIL as the value of thelistener: this behaves as a DDS_SubscriberListener whose operationsperform no action.

in const DDS_StatusMask mask - a bit-mask in which each bit enables theinvocation of the DDS_SubscriberListener for a certain status.

Return ValueDDS_Subscriber - Return value is a pointer to the newly-created

DDS_Subscriber. In case of an error, the DDS_OBJECT_NIL pointer isreturned.

Detailed DescriptionThis operation creates a DDS_Subscriber with the desired QosPolicy settingsand if applicable, attaches the optionally specified DDS_SubscriberListener toit. When the DDS_SubscriberListener is not applicable, the DDS_OBJECT_NILpointer must be supplied instead. To delete the DDS_Subscriber the operationDDS_DomainParticipant_delete_subscriber o r DDS_DomainParticipant_delete_contained_entities must be used.

174API Reference

3 DCPS Classes and Operations 3.2 Domain Module

In case the specified QosPolicy settings are not consistent, no DDS_Subscriberis created and the DDS_OBJECT_NIL pointer is returned. DDS_OBJECT_NIL canalso be returned when insufficient access rights exist for the partition(s) listed in theprovided QoS structure.

Default QoSThe constant DDS_SUBSCRIBER_QOS_DEFAULT can be used as parameter qos tocreate a DDS_Subscriber with the default DDS_SubscriberQos as set in theDomainparticipant. The effect of using DDS_SUBSCRIBER_QOS_DEFAULT ist h e s a m e a s c a l l i n g th e o p e r a t i o nDDS_DomainParticipant_get_default_subscriber_qos and using theresulting DDS_SubscriberQos to create the DDS_Subscriber.

Communication StatusFor each communication status, the StatusChangedFlag flag is initially set toFALSE. It becomes TRUE whenever that communication status changes. For eachcommun ica t i on s t a t u s a c t i va t ed i n t he mask , t h e a s soc i a t e dDDS_SubscriberListener operation is invoked and the communication status isreset to FALSE, as the listener implicitly accesses the status which is passed as aparameter to that operation. The fact that the status is reset prior to calling thelistener means that if the application calls the get_<status_name>_status frominside the listener it will see the status already reset. The following statuses are applicable to the DDS_SubscriberListener:• DDS_REQUESTED_DEADLINE_MISSED_STATUS (propagated)• DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS (propagated)• DDS_SAMPLE_LOST_STATUS (propagated)• DDS_SAMPLE_REJECTED_STATUS (propagated)• DDS_DATA_AVAILABLE_STATUS (propagated)• DDS_LIVELINESS_CHANGED_STATUS (propagated)• DDS_SUBSCRIPTION_MATCHED_STATUS (propagated)• DDS_DATA_ON_READERS_STATUS

Be aware that the DDS_SUBSCRIPTION_MATCHED_STATUS is not applicable whenthe infrastructure does not have the information available to determine connectivity.This is the case when OpenSplice is configured not to maintain discoveryinformation in the Networking Service. (See also the description of theNetworkService/Discovery[@enabled] attribute in section 4.4.1.6.1on page 244 of the Deployment Guide.) In this case the operation will returnDDS_OBJECT_NIL.

175API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Status bits are declared as a constant and can be used by the application in an ORoperation to create a tailored mask. The special constant DDS_STATUS_MASK_NONEcan be used to indicate that the created entity should not respond to any of itsavailable statuses. The DDS will therefore attempt to propagate these statuses to itsfactory. The special constant DDS_STATUS_MASK_ANY_V1_2 can be used to selectall applicable statuses specified in the “Data Distribution Service for Real-timeSystems Version 1.2” specification.

Status PropagationThe Data Distribution Service will trigger the most specific and relevant Listener.In other words, in case a communication status is also activated on theDDS_DataReaderListener o f a conta ined DDS_DataReader, theDDS_DataReaderListener on that contained DDS_DataReader is invokedinstead of the DDS_SubscriberListener. This means that a status change on acontained DDS_DataReader only invokes the DDS_SubscriberListener if thecontained DDS_DataReader itself does not handle the trigger event generated bythe status change.In case a communica t ion s ta tus i s not ac t iva ted in the mask o f theDDS_SubscriberListener, the DDS_DomainParticipantListener of thecontaining DDS_DomainParticipant is invoked (if attached and activated for thestatus that occurred). This allows the application to set a default behaviour in theDDS_DomainParticipantListener o f t h e c o n t a i n i n gDDS_DomainParticipant and a DDS_Subscriber specific behaviour whenneeded. In case the DDS_DomainParticipantListener is also not attached orthe communication status is not activated in its mask, the application is not notifiedof the change.The s t a t u se s DDS_DATA_ON_READERS_STATUS a n d DDS_DATA_AVAILABLE_STATUS are “Read Communication Statuses” and are an exception toall other plain communication statuses: they have no corresponding status structurethat can be obtained with a get_<status_name>_status operation and they aremutually exclusive. When new information becomes available to a DataReader, theData Distribution Service will f irst look in an attached and activatedDDS_SubscriberListener or DDS_DomainParticipantListener (in thato r d e r ) f o r t h e DDS_DATA_ON_READERS_STATUS . I n c a s e t h eDDS_DATA_ON_READERS_STATUS can not be handled, the Data DistributionService will look in an attached and activated DDS_DataReaderListener,DDS_SubscriberListener or DDS_DomainParticipantListener for theDDS_DATA_AVAILABLE_STATUS (in that order).

176API Reference

3 DCPS Classes and Operations 3.2 Domain Module

3.2.1.7 DDS_DomainParticipant_create_topic

Synopsis#include <dds_dcps.h>DDS_Topic DDS_DomainParticipant_create_topic (DDS_DomainParticipant _this, const DDS_char *topic_name, const DDS_char *type_name, const DDS_TopicQos *qos, const struct DDS_TopicListener *a_listener, const DDS_StatusMask mask);

DescriptionThis operation creates a pointer to a new or existing DDS_Topic under the givenname, for a specific type, with the desired QosPolicy settings and if applicable,attaches the optionally specified DDS_TopicListener to it.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant

object on which the operation is operated.in const DDS_char *topic_name - the name of the DDS_Topic to be created.

A new DDS_Topic will only be created, when no DDS_Topic, with the samename, is found within the DDS_DomainParticipant.

in const DDS_char *type_name - a local alias of the data type, which musthave been registered before creating the DDS_Topic.

in const DDS_TopicQos *qos - a collection of QosPolicy settings for thenew DDS_Topic. In case these settings are not self consistent, no DDS_Topicis created.

in const struct DDS_TopicListener *a_listener - a pointer to theDDS_TopicListener instance which will be attached to the new DDS_Topic.It is permitted to use DDS_OBJECT_NIL as the value of the listener: thisbehaves as a DDS_TopicListener whose operations perform no action.

in const DDS_StatusMask mask - a bit-mask in which each bit enables theinvocation of the DDS_TopicListener for a certain status.

Return ValueDDS_Topic - Return value is a pointer to the new or existing DDS_Topic. In case

of an error, the DDS_OBJECT_NIL pointer is returned.

177API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Detailed DescriptionThis operation creates a pointer to a new or existing DDS_Topic under the givenname, for a specific type, with the desired QosPolicy settings and if applicable,attaches the optionally specified DDS_TopicListener to it. When theDDS_TopicListener is not applicable, the DDS_OBJECT_NIL pointer must besupplied instead. In case the specified QosPolicy settings are not consistent, noDDS_Topic is created and the DDS_OBJECT_NIL pointer is returned. To delete theDDS_Topic the operation DDS_DomainParticipant_delete_topic orDDS_DomainParticipant_delete_contained_entities must be used.

Default QoSThe constant DDS_TOPIC_QOS_DEFAULT can be used as parameter qos to create aDDS_Topic w i t h t h e d e f a u l t DDS_TopicQos a s s e t i n t heDDS_DomainParticipant. The effect of using DDS_TOPIC_QOS_DEFAULT is thes a m e a s c a l l i n g t h e o p e r a t i o nDDS_DomainParticipant_get_default_topic_qos and using the resultingDDS_TopicQos to create the DDS_Topic.The DDS_Topic is bound to the type type_name. Prior to creating theDDS_Topic, the type_name must have been registered with the Data DistributionService. Registering the type_name is done using the data type specificDDS_TypeSupport_register_type operation.

Existing DDS_Topic nameB e f o r e c r e a t i n g a n e w DDS_Topic , t h i s o p e r a t i o n p e r f o r m s aDDS_DomainParticipant_lookup_topicdescription for the specifiedtopic_name. When a DDS_Topic is found with the same name in the currentdomain, the QoS and type_name of the found DDS_Topic are matched against theparameters qos and type_name. When they are the same, no DDS_Topic iscreated but a new proxy of the existing DDS_Topic is returned. When they are notexactly the same, no DDS_Topic is created and the DDS_OBJECT_NIL pointer isreturned.When a DDS_Topic is obtained multiple times, it must also be deleted that samenumber of times using DDS_DomainParticipant_delete_topic or callingDDS_DomainParticipant_delete_contained_entities once to delete allthe proxies.

Local proxySince a DDS_Topic is a global concept in the system, access is provided through alocal proxy. In other words, the pointer returned is actually not a pointer to aDDS_Topic but to a locally created proxy. The Data Distribution Servicepropagates DDS_Topics and makes remotely created DDS_Topics locally

178API Reference

3 DCPS Classes and Operations 3.2 Domain Module

available through this proxy. For each create, a new proxy is created. Therefore theDDS_Topic must be deleted the same number of times, as the DDS_Topic wascreated with the same topic_name per Domain. In other words, each pointer (localproxy) must be deleted separately.

Communication StatusFor each communication status, the StatusChangedFlag flag is initially set toFALSE. It becomes TRUE whenever that communication status changes. For eachcommunication status activated in the mask, the associated DDS_TopicListeneroperation is invoked and the communication status is reset to FALSE, as the listenerimplicitly accesses the status which is passed as a parameter to that operation. Thefact that the status is reset prior to calling the listener means that if the applicationcalls the get_<status_name>_status from inside the listener it will see thestatus already reset.The following statuses are applicable to the DDS_TopicListener:• DDS_INCONSISTENT_TOPIC_STATUS Status bits are declared as a constant and can be used by the application in an ORoperation to create a tailored mask. The special constant DDS_STATUS_MASK_NONEcan be used to indicate that the created entity should not respond to any of itsavailable statuses. The DDS will therefore attempt to propagate these statuses to itsfactory. The special constant DDS_STATUS_MASK_ANY_V1_2 can be used to selectall statuses specified in the “Data Distribution Service for Real-time SystemsVersion 1.2” specification.

Status PropagationIn case a communica t ion s ta tus i s not ac t iva ted in the mask o f theDDS_TopicListener, the DDS_DomainParticipantListener of thecontaining DDS_DomainParticipant is invoked (if attached and activated for thestatus that occurred). This allows the application to set a default behaviour in theDDS_DomainParticipantListener o f t h e c o n t a i n i n gDDS_DomainParticipant and a DDS_Topic specific behaviour when needed. Incase the DDS_DomainParticipantListener is also not attached or thecommunication status is not activated in its mask, the application is not notified ofthe change.

3.2.1.8 DDS_DomainParticipant_delete_contained_entities

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_delete_contained_entities (DDS_DomainParticipant _this);

179API Reference

3 DCPS Classes and Operations 3.2 Domain Module

DescriptionThis operation deletes all of the DDS_Entity objects that were created on theDDS_DomainParticipant.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant

object on which the operation is performed.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_ALREADY_DELETED , DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionThis operation deletes all the DDS_Entity objects that were created on theDDS_DomainParticipant. In other words, it deletes all DDS_Publisher,DDS_Subscriber, DDS_Topic , DDS_ContentFilteredTopic andDDS_MultiTopic objects. Prior to deleting each contained DDS_Entity, thisope ra t i on r e g re s s ive ly c a l l s t h e c o r r e s p o n d i n gDDS_<Entity>_delete_contained_entities operat ion on eachDDS_Entity (if applicable). In other words, all DDS_Entity objects in theDDS_Publisher and DDS_Subscriber a re de le ted , inc luding theDDS_DataWriter and DDS_DataReader. Also the DDS_QueryCondition andDDS_ReadCondition objects contained by the DDS_DataReader are deleted.

DDS_TopicSince a DDS_Topic is a global concept in the system, access is provided through alocal proxy. The Data Distribution Service propagates DDS_Topics and makesremotely created DDS_Topics locally available through this proxy. Such a proxy isc r e a t e d b y t h e DDS_DomainParticipant_create_topic o rDDS_DomainParticipant_find_topic operation. When a pointer to the sameDDS_Topic w a s c r e a t e d m u l t i p l e t i m e s ( e i t h e r b yDDS_DomainParticipant_create_topic o rDDS_DomainParticipant_find_topic), all pointers (local proxies) are deleted.With the last proxy, the DDS_Topic itself is also removed from the system.

NOTE: The operation will return DDS_PRECONDITION_NOT_MET if the any of thecontained entities is in a state where it cannot be deleted. This will occur, forexample, if a contained DDS_DataReader cannot be deleted because theapplication has called a read or take operation and has not called the

180API Reference

3 DCPS Classes and Operations 3.2 Domain Module

corresponding return_loan operation to return the loaned samples. In such cases,the operation does not roll back any entity deletions performed prior to the detectionof the problem.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the contained DDS_Entity objects are deleted and the

application may delete the DDS_DomainParticipant.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_DomainParticipant has

already been deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_PRECONDITION_NOT_MET - one or more of the contained entities

are in a state where they cannot be deleted.

3.2.1.9 DDS_DomainParticipant_delete_contentfilteredtopic

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_delete_contentfilteredtopic (DDS_DomainParticipant _this, const DDS_ContentFilteredTopic

a_contentfilteredtopic);

DescriptionThis operation deletes a DDS_ContentFilteredTopic.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant

object on which the operation is operated.in const DDS_ContentFilteredTopic a_contentfilteredtopic - a

pointer to the DDS_ContentFilteredTopic, which is to be deleted.

181API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_ALREADY_DELETED , DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionThis operation deletes a DDS_ContentFilteredTopic.The deletion of a DDS_ContentFilteredTopic is not allowed if there are anye x i s t i n g DDS_DataReader o b j e c t s t h a t a r e u s i n g t h eDDS_ContentFilteredTopic. If the DDS_DomainParticipant_delete_contentfilteredtopic operationis called on a DDS_ContentFilteredTopic with existing DDS_DataReaderobjects attached to it, it will return PRECONDITION_NOT_MET.The DDS_DomainParticipant_delete_contentfilteredtopic operationmust be called on the same DDS_DomainParticipant object used to create theDDS_ContentFilteredTopic.If DDS_DomainParticipant_delete_contentfilteredtopic is called on adifferent DDS_DomainParticipant the operation will have no effect and it willreturn PRECONDITION_NOT_MET.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the DDS_ContentFilteredTopic is deleted.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter a_contentfilteredtopic

is not a valid DDS_ContentFilteredTopic.• DDS_RETCODE_ALREADY_DELETED - the DDS_DomainParticipant has

already been deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_PRECONDITION_NOT_MET - the operation is called on a differentDDS_DomainParticipant, as used when the DDS_ContentFilteredTopicwas created, or the DDS_ContentFilteredTopic is being used by one or moreDDS_DataReader objects.

182API Reference

3 DCPS Classes and Operations 3.2 Domain Module

3.2.1.10 DDS_DomainParticipant_delete_multitopic

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_delete_multitopic (DDS_DomainParticipant _this, const DDS_MultiTopic a_multitopic);

NOTE: This operation is not yet implemented. It is scheduled for a future release.

DescriptionThis operation deletes a DDS_MultiTopic.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant

object on which the operation is operated.in const DDS_MultiTopic a_multitopic - a po in te r to the

DDS_MultiTopic, which is to be deleted.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_ALREADY_DELETED , DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionThis operation deletes a DDS_MultiTopic.The deletion of a DDS_MultiTopic is not allowed if there are any existingDDS_DataReader objects that are using the DDS_MultiTopic . If theDDS_DomainParticipant_delete_multitopic operation is called on aDDS_MultiTopic with existing DDS_DataReader objects attached to it, it willreturn DDS_RETCODE_PRECONDITION_NOT_MET.The DDS_DomainParticipant_delete_multitopic operation must be calledon the same DDS_DomainParticipant ob jec t u sed to c rea t e t heDDS_MultiTopic. If DDS_DomainParticipant_delete_multitopic iscalled on a different DDS_DomainParticipant the operation will have no effectand it will return DDS_RETCODE_PRECONDITION_NOT_MET.

Return CodeWhen the operation returns:

183API Reference

3 DCPS Classes and Operations 3.2 Domain Module

• DDS_RETCODE_OK - the DDS_MultiTopic is deleted.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter a_multitopic is not a validDDS_MultiTopic.

• DDS_RETCODE_ALREADY_DELETED - the DDS_DomainParticipant hasalready been deleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_PRECONDITION_NOT_MET - the operation is called on a differentDDS_DomainParticipant, as used when the DDS_MultiTopic was created, orthe DDS_MultiTopic is being used by one or more DDS_DataReader objects.

3.2.1.11 DDS_DomainParticipant_delete_publisher

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_delete_publisher (DDS_DomainParticipant _this, const DDS_Publisher p);

DescriptionThis operation deletes a DDS_Publisher.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant

object on which the operation is operated.in const DDS_Publisher p - a pointer to the DDS_Publisher, which is to

be deleted.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_ALREADY_DELETED , DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_PRECONDITION_NOT_MET.

184API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Detailed DescriptionThis operation deletes a DDS_Publisher. A DDS_Publisher cannot be deletedwhen it has any attached DDS_DataWriter objects. When the operation is calledon a DDS_Publisher with DDS_DataWriter objects, the operation returnsDDS_RETCODE_PRECONDITION_NOT_MET. When the operation is called on adifferent DDS_DomainParticipant, as used when the DDS_Publisher wasc r e a t e d , t h e o p e r a t i o n h a s n o e ff e c t a n d r e t u r n sDDS_RETCODE_PRECONDITION_NOT_MET.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the DDS_Publisher is deleted.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter p is not a validDDS_Publisher.

• DDS_RETCODE_ALREADY_DELETED - the DDS_DomainParticipant hasalready been deleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_PRECONDITION_NOT_MET - the operation is called on a differentDDS_DomainParticipant, as used when the DDS_Publisher was created, orthe DDS_Publisher contains one or more DDS_DataWriter objects.

3.2.1.12 DDS_DomainParticipant_delete_subscriber

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_delete_subscriber (DDS_DomainParticipant _this, const DDS_Subscriber s);

DescriptionThis operation deletes a DDS_Subscriber.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant object

on which the operation is operated.

185API Reference

3 DCPS Classes and Operations 3.2 Domain Module

in const DDS_Subscriber s - a pointer to the DDS_Subscriber, which isto be deleted.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_ALREADY_DELETED , DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionThis operation deletes a DDS_Subscriber. A DDS_Subscriber cannot be deletedwhen it has any attached DDS_DataReader objects. When the operation is calledon a DDS_Subscriber with DDS_DataReader objects, the operation returnsDDS_RETCODE_PRECONDITION_NOT_MET. When the operation is called on adifferent DDS_DomainParticipant, as used when the DDS_Subscriber wasc r e a t e d , t h e o p e r a t i o n h a s n o e ff e c t a n d r e t u r n sDDS_RETCODE_PRECONDITION_NOT_MET.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the DDS_Subscriber is deleted.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter s is not a validDDS_Subscriber.

• DDS_RETCODE_ALREADY_DELETED - the DDS_DomainParticipant hasalready been deleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_PRECONDITION_NOT_MET - the operation is called on a differentDDS_DomainParticipant, as used when the DDS_Subscriber was created, orthe DDS_Subscriber contains one or more DDS_DataReader objects.

3.2.1.13 DDS_DomainParticipant_delete_topic

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t

186API Reference

3 DCPS Classes and Operations 3.2 Domain Module

DDS_DomainParticipant_delete_topic (DDS_DomainParticipant _this, const DDS_Topic a_topic);

DescriptionThis operation deletes a DDS_Topic.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant

object on which the operation is operated.in const DDS_Topic a_topic - a pointer to the DDS_Topic, which is to be

deleted.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_ALREADY_DELETED , DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionThis operation deletes a DDS_Topic. A DDS_Topic cannot be deleted when thereare any DDS_DataReader, DDS_DataWriter, DDS_ContentFilteredTopic orDDS_MultiTopic objects, which are using the DDS_Topic. When the operation iscalled on a DDS_Topic pointed to by any of these objects, the operation returnsDDS_RETCODE_PRECONDITION_NOT_MET. When the operation is called on adifferent DDS_DomainParticipant, as used when the DDS_Topic was created,the operation has no effect and returns DDS_RETCODE_PRECONDITION_NOT_MET.

Local ProxySince a DDS_Topic is a global concept in the system, access is provided through alocal proxy. In other words, the pointer is actually not a pointer to a DDS_Topic butto the local proxy. The Data Distribution Service propagates DDS_Topics andmakes remotely created DDS_Topics locally available through this proxy. Such aproxy is created by the DDS_DomainParticipant_create_topic orDDS_DomainParticipant_find_topic operation. This operation will delete thelocal proxy. When a pointer to the same DDS_Topic was created multiple times( e i t h e r b y DDS_DomainParticipant_create_topic o rDDS_DomainParticipant_find_topic), each pointer (local proxy) must bedeleted separately. When this proxy is the last proxy for this DDS_Topic, the

187API Reference

3 DCPS Classes and Operations 3.2 Domain Module

DDS_Topic itself is also removed from the system. As mentioned, a proxy mayonly be deleted when there are no other entities attached to it. However, it ispossible to delete a proxy while there are entities attached to a different proxy.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the DDS_Topic is deleted.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter a_topic is not a validDDS_Topic.

• DDS_RETCODE_ALREADY_DELETED - the DDS_DomainParticipant hasalready been deleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_PRECONDITION_NOT_MET - the operation is called on a differentDDS_DomainParticipant, as used when the DDS_Topic was created, or theDDS_Topic is still pointed to by other objects.

3.2.1.14 DDS_DomainParticipant_enable (inherited)This operation is inherited and therefore not described here. See the classDDS_Entity for further explanation.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_enable (DDS_DomainParticipant _this);

3.2.1.15 DDS_DomainParticipant_find_topic

Synopsis#include <dds_dcps.h>DDS_Topic DDS_DomainParticipant_find_topic (DDS_DomainParticipant _this, const DDS_char *topic_name, const DDS_Duration_t *timeout);

188API Reference

3 DCPS Classes and Operations 3.2 Domain Module

DescriptionThis operation gives access to an existing (or ready to exist) enabled DDS_Topic,based on its topic_name.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant object

on which the operation is operated.in const DDS_char *topic_name - the name of the DDS_Topic that the

application wants access to.in const DDS_Duration_t *timeout - the maximum duration to block for

the DDS_DomainParticipant_find_topic, after which the applicationthread is unblocked. The special constant DDS_DURATION_INFINITE can beused when the maximum waiting time does not need to be bounded.

Return ValueDDS_Topic - Return value is a pointer to the DDS_Topic found.

Detailed DescriptionThis operation gives access to an existing DDS_Topic, based on its topic_name.The operation takes as arguments the topic_name of the DDS_Topic and atimeout.If a DDS_Topic of the same topic_name already exists, it gives access to thisDDS_Topic. Otherwise it waits (blocks the caller) until another mechanism createsit. This other mechanism can be another thread, a configuration tool, or some otherData Distribution Service utility. If after the specified timeout the DDS_Topic canstill not be found, the caller gets unblocked and DDS_HANDLE_NIL is returned.A DDS_Topic obtained by means of DDS_DomainParticipant_find_topic,must also be deleted by means of DDS_DomainParticipant_delete_topic sothat the local resources can be released. If a DDS_Topic is obtained multiple timesi t m u s t a l s o b e d e l e t e d t h a t s a m e n u m b e r o f t i m e s u s i n gDDS_DomainParticipant_delete_topic o r c a l l i n gDDS_DomainParticipant_delete_contained_entities once to delete allthe proxies.A DDS_Topic t h a t i s ob t a in e d b y m e a n s o fDDS_DomainParticipant_find_topic i n a s p e c i f i cDDS_DomainParticipant can only be used to create DDS_DataReaders andDDS_DataWriters in that DDS_DomainParticipant if its correspondingDDS_TypeSupport has been registered to that same DDS_DomainParticipant.

189API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Local ProxySince a DDS_Topic is a global concept in the system, access is provided through alocal proxy. In other words, the pointer returned is actually not a pointer to aDDS_Topic but to a locally created proxy. The Data Distribution Servicepropagates DDS_Topics and makes remotely created DDS_Topics locallyavailable through this proxy. For each time this operation is called, a new proxy iscreated. Therefore the DDS_Topic must be deleted the same number of times, as theDDS_Topic was created with the same topic_name per Domain. In other words,each pointer (local proxy) must be deleted separately.

3.2.1.16 DDS_DomainParticipant_get_builtin_subscriber

Synopsis#include <dds_dcps.h>DDS_Subscriber DDS_DomainParticipant_get_builtin_subscriber (DDS_DomainParticipant _this);

DescriptionThis operation returns the built-in DDS_Subscriber associated with theDDS_DomainParticipant.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant

object on which the operation is operated.

Return ValueDDS_Subscriber - Result value is a pointer to the built-in DDS_Subscriber

associated with the DDS_DomainParticipant.

Detailed DescriptionThis operation returns the built-in DDS_Subscriber associated with theDDS_DomainParticipant. Each DDS_DomainParticipant contains severalbuilt-in DDS_Topic objects. The built-in DDS_Subscriber contains thecorresponding DDS_DataReader ob jec ts to access them. Al l theseDDS_DataReader objects belong to a single built-in DDS_Subscriber. Note thatthere is exactly one buil t - in DDS_Subscriber associated with eachDDS_DomainParticipant.

3.2.1.17 DDS_DomainParticipant_get_current_time

Synopsis#include <dds_dcps.h>

190API Reference

3 DCPS Classes and Operations 3.2 Domain Module

DDS_ReturnCode_t get_current_time (DDS_DomainParticipant _this, DDS_Time_t *current_time);

DescriptionThis operation returns the value of the current time that the Data DistributionService uses to time-stamp written data as well as received data in current_time.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant object

on which the operation is operated.inout DDS_Time_t *current_time - the value of the current time as used by

the Data Distribution System. The input value of current_time is ignored.

Return ValueDDS_ReturnCode_t - Possible return codes of the operation are:DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED , DDS_RETCODE_OUT_OF_RESOURCES o rDDS_RETCODE_NOT_ENABLED.

Detailed DescriptionThis operation returns the value of the current time that the Data DistributionService uses to time-stamp written data as well as received data in current_time.The input value of current_time is ignored by the operation.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the value of the current time is returned in current_time.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter current_time is not a valid

reference.• DDS_RETCODE_ALREADY_DELETED - the DomainParticipant has already

been deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_NOT_ENABLED - the DDS_DomainParticipant is not enabled.

191API Reference

3 DCPS Classes and Operations 3.2 Domain Module

3.2.1.18 DDS_DomainParticipant_get_default_publisher_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_get_default_publisher_qos (DDS_DomainParticipant _this, DDS_PublisherQos *qos);

DescriptionThis operation gets the struct with the default DDS_Publisher QosPolicysettings of the DDS_DomainParticipant.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant object

on which the operation is operated.inout DDS_PublisherQos *qos - a pointer to the DDS_PublisherQos struct

(provided by the application) in which the default QosPolicy settings for theDDS_Publisher are written.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_ALREADY_DELETED , DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionThis operation gets the struct with the default DDS_Publisher QosPolicysettings of the DDS_DomainParticipant (that is the DDS_PublisherQos)which is used for newly-created DDS_Publisher objects, in case the constantDDS_PUBLISHER_QOS_DEFAULT is used. The default DDS_PublisherQos is onlyused when the constant is suppl ied as parameter qos to specify theDDS_PublisherQos in the DDS_DomainParticipant_create_publisheroperation. The application must provide the DDS_PublisherQos struct in whichthe QosPolicy settings can be stored and pass the qos pointer to the operation.The operation writes the default QosPolicy settings to the struct pointed to by qos.Any settings in the struct are overwritten.The values retrieved by this operation match the set of values specified on the lastsuccessful call to DDS_DomainParticipant_set_default_publisher_qos,or, if the call was never made, the default values as specified for each QosPolicysetting as defined in Table 5: on page 65.

192API Reference

3 DCPS Classes and Operations 3.2 Domain Module

NOTE: The operation will return DDS_PRECONDITION_NOT_MET if the any of thecontained entities is in a state where it cannot be deleted. This will occur, forexample, if a contained DDS_DataReader cannot be deleted because theapplication has called a read or take operation and has not called thecorresponding return_loan operation to return the loaned samples. In such cases,the operation does not roll back any entity deletions performed prior to the detectionof the problem.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the default DDS_Publisher QosPolicy settings of thisDDS_DomainParticipant have successfully been copied into the specifiedDDS_PublisherQos parameter.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_DomainParticipant has

already been deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_PRECONDITION_NOT_MET - one or more of the contained entities

are in a state where they cannot be deleted.

3.2.1.19 DDS_DomainParticipant_get_default_subscriber_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_get_default_subscriber_qos (DDS_DomainParticipant _this, DDS_SubscriberQos *qos);

DescriptionThis operation gets the struct with the default DDS_Subscriber QosPolicysettings of the DDS_DomainParticipant.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant object

on which the operation is operated.

193API Reference

3 DCPS Classes and Operations 3.2 Domain Module

inout DDS_SubscriberQos *qos - a pointer to the QosPolicy struct(provided by the application) in which the default QosPolicy settings for theDDS_Subscriber is written.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation gets the struct with the default DDS_Subscriber QosPolicysettings of the DDS_DomainParticipant (that is the DDS_SubscriberQos)which is used for newly-created DDS_Subscriber objects, in case the constantDDS_SUBSCRIBER_QOS_DEFAULT is used. The default DDS_SubscriberQos isonly used when the constant is supplied as parameter qos to specify theDDS_SubscriberQos in the DDS_DomainParticipant_create_subscriberoperation. The application must provide the QoS struct in which the policy can bestored and pass the qos pointer to the operation. The operation writes the defaultQosPolicy to the struct pointed to by qos. Any settings in the struct areoverwritten.The values retrieved by this operation match the set of values specified on the lastsuccessful call to DDS_DomainParticipant_set_default_subscriber_qos,or, if the call was never made, the default values as specified for each QosPolicydefined in Table 5: on page 65.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the default DDS_Subscriber QosPolicy settings of thisDDS_DomainParticipant have successfully been copied into the specifiedDDS_SubscriberQos parameter.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_DomainParticipant has

already been deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

194API Reference

3 DCPS Classes and Operations 3.2 Domain Module

3.2.1.20 DDS_DomainParticipant_get_default_topic_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_get_default_topic_qos (DDS_DomainParticipant _this, DDS_TopicQos *qos);

DescriptionThis operation gets the struct with the default DDS_Topic QosPolicy settings ofthe DDS_DomainParticipant.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant object

on which the operation is operated.inout DDS_TopicQos *qos - a pointer to the QosPolicy struct (provided by

the application) in which the default QosPolicy settings for the DDS_Topic iswritten.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation gets the struct with the default DDS_Topic QosPolicy settings ofthe DDS_DomainParticipant (that is the DDS_TopicQos) which is used forne wly -c r ea t ed DDS_Topic ob j ec t s , i n c a se t he c ons t a n tDDS_TOPIC_QOS_DEFAULT is used. The default DDS_TopicQos is only used whenthe constant is supplied as parameter qos to specify the DDS_TopicQos in theDDS_DomainParticipant_create_topic operation. The application mustprovide the QoS struct in which the policy can be stored and pass the qos pointer tothe operation. The operation writes the default QosPolicy to the struct pointed toby qos. Any settings in the struct are overwritten.The values retrieved by this operation match the set of values specified on the lastsuccessful call to DDS_DomainParticipant_set_default_topic_qos, or, ifthe call was never made, the default values as specified for each QosPolicydefined in Table 5: on page 65.

195API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the default DDS_Topic QosPolicy settings of thisDDS_DomainParticipant have successfully been copied into the specifiedDDS_TopicQos parameter.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_DomainParticipant has

already been deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

3.2.1.21 DDS_DomainParticipant_get_discovered_participants

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_get_discovered_participants (DDS_DomainParticipant _this, DDS_InstanceHandleSeq *participant_handles);

DescriptionThis operation retrieves the list of DomainParticipants that have beendiscovered in the domain.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant object

on which the operation is operated.inout InstanceHandleSeq *participant_handles - a sequence which is

used to pass the list of all associated participants.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK , DDS_RETCODE_ERROR ,DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_UNSUPPORTED,DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, orDDS_RETCODE_NOT_ENABLED.

196API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Detailed DescriptionThis operation retrieves the list of DomainParticipants that have beendiscovered in the domain and that the application has not indicated should be“ignored” by means of the DomainParticipant ignore_participant operation.The participant_handles sequence and its buffer may be pre-allocated by theapplication and therefore must either be re-used in a subsequent invocation of theDDS_DomainParticipant_get_discovered_participants operation or bereleased by calling DDS_free on the returned participant_handles. If thepre-allocated sequence is not big enough to hold the number of associatedparticipants, the sequence will automatically be (re-)allocated to fit the requiredsize.The handles returned in the participant_handles sequence are the ones that areused by the DDS implementation to locally identify the corresponding matchedParticipant entities. You can access more detailed information about a particularp a r t i c i p a n t b y p a s s i n g i t s participant_handle t o e i t h e r t h eDDS_DomainParticipant_get_discovered_participant_data operationor to the DDS_ParticipantBuiltinTopicDataDataReader_read_instanceoperation on the built-in reader for the “DCPSParticipant” topic.Be aware that since DDS_InstanceHandle_t is an opaque datatype, it does notn e c e s s a r i l y m e a n t h a t t h e h a n d l e s o b t a i n e d f r o m t h eDDS_DomainParticipant_get_discovered_participants operation havethe same value as the ones that appear in the instance_handle field of theDDS_SampleInfo when retrieving the participant info through corresponding“DCPSParticipant” built-in reader. You can’t just compare two handles todetermine whether they represent the same participant. If you want to know whethertwo handles actually do represent the same participant, use both handles to retrievetheir corresponding DDS_ParticipantBuiltinTopicData samples and thencompare the key field of both samples.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the list of associated participants has been successfully

obtained.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_UNSUPPORTED - OpenSplice is configured not to maintain the

information about “associated” participants.

197API Reference

3 DCPS Classes and Operations 3.2 Domain Module

• DDS_RETCODE_ALREADY_DELETED - the DDS_DomainParticipant hasalready been deleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_NOT_ENABLED - the DDS_DomainParticipant is not enabled.

3.2.1.22 DDS_DomainParticipant_get_discovered_participant_data

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_get_discovered_participant_data (DDS_DomainParticipant _this, DDS_ParticipantBuiltinTopicData *participant_data, DDS_InstanceHandle_t handle);

DescriptionThis operation retrieves information on a DomainParticipant that has beendiscovered on the network. The participant must be in the same domain as theparticipant on which this operation is invoked and must not have been “ignored” bymeans of the DomainParticipant ignore_participant operation.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant object

on which the operation is operated.inout DDS_ParticipantBuiltinTopicData *participant_data - a

pointer to the sample in which the information about the specified partition is tobe stored.

in const DDS_InstanceHandle_t participant_handle - a handle to theparticipant whose information needs to be retrieved.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK , DDS_RETCODE_ERROR ,DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_UNSUPPORTED,DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, orDDS_RETCODE_NOT_ENABLED.

198API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Detailed DescriptionThis operation retrieves information on a DomainParticipant that has beendiscovered on the network. The participant must be in the same domain as theparticipant on which this operation is invoked and must not have been “ignored” bymeans of the DomainParticipant ignore_participant operation.The partition_handle must correspond to a partition currently associated withthe DDS_DomainParticipant, otherwise the operation will fail and returnDDS_RETCODE_ERROR . T h e o p e r a t i o nDDS_DomainParticipant_get_discovered_participant_data can beused to find more detailed information about a particular participant than is foundwith the DDS_DomainParticipant_get_discovered_participantsoperation.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the information on the specified partition has been

successfully retrieved.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_UNSUPPORTED - OpenSplice is configured not to maintain the

information about “associated” partition.• DDS_RETCODE_ALREADY_DELETED - the DDS_DomainParticipant has

already been deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_NOT_ENABLED - the DDS_DomainParticipant is not enabled.

3.2.1.23 DDS_DomainParticipant_get_discovered_topics

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_get_discovered_topics (DDS_DomainParticipant _this, DDS_InstanceHandleSeq *topic_handles);

DescriptionThis operation retrieves the list of Topics that have been discovered in the domain.

199API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant object

on which the operation is operated.inout InstanceHandleSeq *participant_handles - a sequence which is

used to pass the list of all associated topics.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK , DDS_RETCODE_ERROR ,DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_UNSUPPORTED,DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, orDDS_RETCODE_NOT_ENABLED.

Detailed DescriptionThis operation retrieves the list of Topics that have been discovered in the domainand that the application has not indicated should be “ignored” by means of theDomainParticipant ignore_topic operation.The topic_handles sequence and its buffer may be pre-allocated by theapplication and therefore must either be re-used in a subsequent invocation of theDDS_DomainParticipant_get_discovered_topics operation or be releasedby calling DDS_free on the returned topic_handles. If the pre-allocatedsequence is not big enough to hold the number of associated topics, the sequencewill automatically be (re-)allocated to fit the required size.The handles returned in the topic_handles sequence are the ones that are used bythe DDS implementation to locally identify the corresponding matched Topicentities. You can access more detailed information about a particular topic bypa s s ing i t s topic_handle t o e i t h e r t h eDDS_DomainParticipant_get_discovered_topic_data operation or to theDDS_TopicBuiltinTopicDataDataReader_read_instance operation on thebuilt-in reader for the “DCPSTopic” topic.Be aware that since DDS_InstanceHandle_t is an opaque datatype, it does notn e c e s s a r i l y m e a n t h a t t h e h an d l e s o b t a i n e d f r o m t h eDDS_DomainParticipant_get_discovered_topics operation have the samevalue as the ones that appear in the instance_handle f ie ld of theDDS_SampleInfo when retrieving the participant info through corresponding“DCPSTopic” built-in reader. You can’t just compare two handles to determinewhether they represent the same topic. If you want to know whether two handlesactually do represent the same topic, use both handles to retrieve theircorresponding DDS_TopicBuiltinTopicData samples and then compare the keyfield of both samples.

200API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the list of associated topics has been successfully obtained.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_UNSUPPORTED - OpenSplice is configured not to maintain the

information about “associated” topics.• DDS_RETCODE_ALREADY_DELETED - the DDS_DomainParticipant has

already been deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_NOT_ENABLED - the DDS_DomainParticipant is not enabled.

3.2.1.24 DDS_DomainParticipant_get_discovered_topic_data

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_get_discovered_topic_data (DDS_DomainParticipant _this, DDS_TopicBuiltinTopicData *topic_data, DDS_InstanceHandle_t handle);

DescriptionThis operation retrieves information on a Topic that has been discovered on thenetwork. The topic have been created by a participant in the same domain as theparticipant on which this operation is invoked and must not have been “ignored” bymeans of the DomainParticipant ignore_topic operation.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant object

on which the operation is operated.inout DDS_ParticipantBuiltinTopicData *topic_data - a pointer to the

sample in which the information about the specified topic is to be stored.in const DDS_InstanceHandle_t topic_handle - a handle to the topic

whose information needs to be retrieved.

201API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK , DDS_RETCODE_ERROR ,DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_UNSUPPORTED,DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, orDDS_RETCODE_NOT_ENABLED.

Detailed DescriptionThis operation retrieves information on a Topic that has been discovered on thenetwork. The topic must have been created by a participant in the same domain asthe participant on which this operation is invoked and must not have been “ignored”by means of the DomainParticipant ignore_topic operation.The topic_handle must correspond to a topic currently associated with theDDS_DomainParticipant, otherwise the operation will fail and returnDDS_RETCODE_ERROR . T h e o p e r a t i o nDDS_DomainParticipant_get_discovered_topic_data can be used to findmore detailed information about a particular topic than is found with theDDS_DomainParticipant_get_discovered_topics operation.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the information on the specified topic has been successfully

retrieved.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_UNSUPPORTED - OpenSplice is configured not to maintain the

information about “associated” topic.• DDS_RETCODE_ALREADY_DELETED - the DDS_DomainParticipant has

already been deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_NOT_ENABLED - the DDS_DomainParticipant is not enabled.

3.2.1.25 DDS_DomainParticipant_get_domain_id

Synopsis#include <dds_dcps.h>DomainId_t DDS_DomainParticipant_get_domain_id

202API Reference

3 DCPS Classes and Operations 3.2 Domain Module

(DDS_DomainParticipant _this);

DescriptionThis opera t ion re turns the DomainId o f the Domain to which th i sDDS_DomainParticipant is attached.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant object

on which the operation is operated.

Return ValueDomainId_t - result is the DomainId.

Detailed DescriptionThis opera t ion re tu rns the DomainId o f the Domain to which th i sDDS_DomainParticipant i s a t t a c h e d . S e e a l s o t h e o p e r a t i o nDDS_DomainParticipantFactory_create_participant (section 3.2.2.1 on page 221).

3.2.1.26 DDS_DomainParticipant_get_listener

Synopsis#include <dds_dcps.h>struct DDS_DomainParticipantListener DDS_DomainParticipant_get_listener (DDS_DomainParticipant _this);

DescriptionThis operation allows access to a DDS_DomainParticipantListener.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant object

on which the operation is operated.

Return Valuestruct DDS_DomainParticipantListener - a p o i n t e r t o t h e

DDS_DomainParticipantListener a t t a c h e d t o t h eDDS_DomainParticipant.

203API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Detailed DescriptionThis operation allows access to a DDS_DomainParticipantListener attachedto th e DDS_DomainParticipant . Wh en n oDDS_DomainParticipantListener was a t t a che d t o t heDDS_DomainParticipant, the DDS_OBJECT_NIL pointer is returned.

3.2.1.27 DDS_DomainParticipant_get_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_get_qos (DDS_DomainParticipant _this, DDS_DomainParticipantQos *qos);

DescriptionThis operation allows access to the existing set of QoS policies for aDDS_DomainParticipant.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant object

on which the operation is operated.inout DDS_DomainParticipantQos *qos - a pointer to the destination

DDS_DomainParticipantQos struct in which the QosPolicy settings willbe copied.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation al lows access to the exist ing set of QoS policies of aDDS_DomainParticipant on wh ich th i s ope r a t ion i s u sed . Th i sDDS_DomainparticipantQos is stored at the location pointed to by the qosparameter.

Return CodeWhen the operation returns:

204API Reference

3 DCPS Classes and Operations 3.2 Domain Module

• DDS_RETCODE_OK - the existing set of QoS policy values applied to thisDDS_DomainParticipant has successfully been copied into the specifiedDDS_DomainParticipantQos parameter.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_DomainParticipant has

already been deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

3.2.1.28 DDS_DomainParticipant_get_status_changes (inherited)This operation is inherited and therefore not described here. See the classDDS_Entity for further explanation.

Synopsis#include <dds_dcps.h>DDS_StatusMask DDS_DomainParticipant_get_status_changes (DDS_DomainParticipant _this);

3.2.1.29 DDS_DomainParticipant_get_statuscondition (inherited)This operation is inherited and therefore not described here. See the classDDS_Entity for further explanation.

Synopsis#include <dds_dcps.h>DDS_StatusCondition DDS_DomainParticipant_get_statuscondition (DDS_DomainParticipant _this);

3.2.1.30 DDS_DomainParticipant_ignore_participant

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_ignore_participant (DDS_DomainParticipant _this, const DDS_InstanceHandle_t handle);

NOTE: This operation is not yet implemented. It is scheduled for a future release.

205API Reference

3 DCPS Classes and Operations 3.2 Domain Module

3.2.1.31 DDS_DomainParticipant_ignore_publication

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_ignore_publication (DDS_DomainParticipant _this, const DDS_InstanceHandle_t handle);

NOTE: This operation is not yet implemented. It is scheduled for a future release.

3.2.1.32 DDS_DomainParticipant_ignore_subscription

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_ignore_subscription (DDS_DomainParticipant _this, const DDS_InstanceHandle_t handle);

NOTE: This operation is not yet implemented. It is scheduled for a future release.

3.2.1.33 DDS_DomainParticipant_ignore_topic

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_ignore_topic (DDS_DomainParticipant _this, const DDS_InstanceHandle_t handle);

NOTE: This operation is not yet implemented. It is scheduled for a future release.

3.2.1.34 DDS_DomainParticipant_lookup_topicdescription

Synopsis#include <dds_dcps.h>DDS_TopicDescription DDS_DomainParticipant_lookup_topicdescription (DDS_DomainParticipant _this, const DDS_char *name);

DescriptionThis operation gives access to a locally-created DDS_TopicDescription, with amatching name.

206API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant object

on which the operation is operated.in const DDS_char *name - the name of the DDS_TopicDescription to

look for.

Return ValueDDS_TopicDescription - R e t u r n v a l u e i s a p o i n t e r t o t h e

DDS_TopicDescription found. When no such DDS_TopicDescription isfound, the DDS_OBJECT_NIL pointer is returned.

Detailed DescriptionThe operation DDS_DomainParticipant_lookup_topicdescription givesaccess to a locally-created DDS_TopicDescription, based on its name. Theoperation takes as argument the name of the DDS_TopicDescription.If one or more local DDS_TopicDescription proxies (also see Section 3.2.1.15,DDS_DomainParticipant_find_topic, on page 188) of the same name already exist,a po in te r to one o f the a l r eady ex i s t ing loca l p rox ies i s r e tu rned :DDS_DomainParticipant_lookup_topicdescription will never create anew local proxy. That means that the proxy that is returned does not need to bedeleted separately from its original. When no local proxy exists, it returns theDDS_OBJECT_NIL pointer. The operation never blocks.The operation DDS_DomainParticipant_lookup_topicdescription may beused to locate any locally-created DDS_Topic, DDS_ContentFilteredTopicand DDS_MultiTopic object.

3.2.1.35 DDS_DomainParticipant_set_default_publisher_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_set_default_publisher_qos (DDS_DomainParticipant _this, const DDS_PublisherQos *qos);

DescriptionThi s ope ra t i on s e t s t he de f au l t DDS_PublisherQos o f t h eDDS_DomainParticipant.

207API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant object

on which the operation is operated.in const DDS_PublisherQos *qos - a collection of QosPolicy settings,

which contains the new default QosPolicy settings for the newly-createdDDS_Publishers.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_UNSUPPORTED, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionT h i s o p e ra t i o n s e t s t h e d e f a u l t DDS_PublisherQos o f t h eDDS_DomainParticipant (that is the struct with the QosPolicy settings) whichis used for newly-created DDS_Publisher objects, in case the constantDDS_PUBLISHER_QOS_DEFAULT is used. The default DDS_PublisherQos is onlyused when the constant is suppl ied as parameter qos to specify theDDS_PublisherQos in the DDS_DomainParticipant_create_publisheroperation. The DDS_PublisherQos is always self consistent, because its policiesdo not depend on each other. This means this operation never returns theDDS_RETCODE_INCONSISTENT_POLICY. The values set by this operation arereturned by DDS_DomainParticipant_get_default_publisher_qos.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the new default DDS_PublisherQos is set.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter qos is not a validDDS_PublisherQos. It contains a QosPolicy setting with an enum value that isoutside its legal boundaries, or a sequence that has inconsistent memory settings.

• DDS_RETCODE_UNSUPPORTED - one or more of the selected QosPolicy valuesare currently not supported by OpenSplice.

• DDS_RETCODE_ALREADY_DELETED - the DDS_DomainParticipant hasalready been deleted.

208API Reference

3 DCPS Classes and Operations 3.2 Domain Module

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

3.2.1.36 DDS_DomainParticipant_set_default_subscriber_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_set_default_subscriber_qos (DDS_DomainParticipant _this, const DDS_SubscriberQos *qos);

DescriptionT h i s o p e r a t i o n s e t s t h e d e f a u l t DDS_SubscriberQos o f t h eDDS_DomainParticipant.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant object

on which the operation is operated.in const DDS_SubscriberQos *qos - a collection of QosPolicy settings,

which contains the new default QosPolicy settings for the newly-createdDDS_Subscribers.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_UNSUPPORTED, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionT h i s o p e r a t i o n s e t s t h e d e f a u l t DDS_SubscriberQos o f t h eDDS_DomainParticipant (that is the struct with the QosPolicy settings) whichis used for newly-created DDS_Subscriber objects, in case the constantDDS_SUBSCRIBER_QOS_DEFAULT is used. The default DDS_SubscriberQos isonly used when the constant is supplied as parameter qos to specify theDDS_SubscriberQos in the DDS_DomainParticipant_create_subscriberoperation. The DDS_SubscriberQos is always self consistent, because its policiesdo not depend on each other. This means this operation never returns theDDS_RETCODE_INCONSISTENT_POLICY. The values set by this operation arereturned by DDS_DomainParticipant_get_default_subscriber_qos.

209API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the new default DDS_SubscriberQos is set.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter qos is not a validDDS_PublisherQos. It contains a QosPolicy setting with an enum value that isoutside its legal boundaries, or a sequence that has inconsistent memory settings.

• DDS_RETCODE_UNSUPPORTED - one or more of the selected QosPolicy valuesare currently not supported by OpenSplice.

• DDS_RETCODE_ALREADY_DELETED - the DDS_DomainParticipant hasalready been deleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

3.2.1.37 DDS_DomainParticipant_set_default_topic_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_set_default_topic_qos (DDS_DomainParticipant _this, const DDS_TopicQos *qos);

DescriptionThis operation sets the default DDS_TopicQos of the DDS_DomainParticipant.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant object

on which the operation is operated.in const DDS_TopicQos *qos - a collection of QosPolicy settings, which

contains the new default QosPolicy settings for the newly-createdDDS_Topics.

210API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_UNSUPPORTED, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_ INCONSISTENT_POLICY.

Detailed DescriptionThis operation sets the default DDS_TopicQos of the DDS_DomainParticipant(that is the struct with the QosPolicy settings) which is used for newly-createdDDS_Topic objects, in case the constant DDS_TOPIC_QOS_DEFAULT is used. Thedefault DDS_TopicQos is only used when the constant is supplied as parameter qosto specify the DDS_TopicQos in the DDS_DomainParticipant_create_topicoperation. This operation checks if the DDS_TopicQos is self consistent. If it is not,the operation has no effect and returns DDS_RETCODE_INCONSISTENT_POLICY.T h e v a l u e s s e t b y t h i s o p e r a t i o n a r e r e t u r n e d b yDDS_DomainParticipant_get_default_topic_qos.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the new default DDS_TopicQos is set.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter qos is not a validDDS_TopicQos. It contains a QosPolicy setting with an invalidDDS_Duration_t value, an enum value that is outside its legal boundaries or asequence that has inconsistent memory settings.

• DDS_RETCODE_UNSUPPORTED - one or more of the selected QosPolicy values arecurrently not supported by OpenSplice.

• DDS_RETCODE_ALREADY_DELETED - the DDS_DomainParticipant hasalready been deleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_INCONSISTENT_POLICY - the parameter qos containsconflicting QosPolicy settings, e.g. a history depth that is higher than thespecified resource limits.

211API Reference

3 DCPS Classes and Operations 3.2 Domain Module

3.2.1.38 DDS_DomainParticipant_set_listener

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_set_listener (DDS_DomainParticipant _this, const struct DDS_DomainParticipantListener

*a_listener, const DDS_StatusMask mask);

DescriptionThis operation attaches a DDS_DomainParticipantListener to theDDS_DomainParticipant.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant object

on which the operation is operated.in const struct DDS_DomainParticipantListener *a_listener - a

pointer to the DDS_DomainParticipantListener instance, which will beattached to the DDS_DomainParticipant.

in const DDS_StatusMask mask - a bit-mask in which each bit enables theinvocation of the DDS_DomainParticipantListener for a certain status.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_UNSUPPORTED , DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_ OUT_OF_RESOURCES.

Detailed DescriptionThis operation attaches a DDS_DomainParticipantListener to theDDS_DomainParticipant. Only one DDS_DomainParticipantListener canb e a t t a c he d t o e a c h DDS_DomainParticipant . I f aDDS_DomainParticipantListener was already attached, the operation willreplace it with the new one. When a_listener is the DDS_OBJECT_NIL pointer, itrepresents a listener that is treated as a NOOP1 for all statuses activated in thebitmask.

1. Short for No-Operation, an instruction that peforms nothing at all.

212API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Communication StatusFor each communication status, the StatusChangedFlag flag is initially set toFALSE. It becomes TRUE whenever that communication status changes. For eachcommun ica t i on s t a t u s a c t i va t ed i n t he mask , t h e a s soc i a t e dDDS_DomainParticipantListener opera t ion i s invoked and thecommunication status is reset to FALSE, as the listener implicitly accesses the statuswhich is passed as a parameter to that operation. The status is reset prior to callingthe listener, so if the application calls the get_<status_name>_status frominside the listener it will see the status already reset. An exception to this rule is theDDS_OBJECT_NIL listener, which does not reset the communication statuses forwhich it is invoked. The following statuses are applicable to the DDS_DomainParticipantListener:• DDS_INCONSISTENT_TOPIC_STATUS (propagated)• DDS_OFFERED_DEADLINE_MISSED_STATUS (propagated)• DDS_REQUESTED_DEADLINE_MISSED_STATUS (propagated)• DDS_OFFERED_INCOMPATIBLE_QOS_STATUS (propagated)• DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS (propagated)• DDS_SAMPLE_LOST_STATUS (propagated)• DDS_SAMPLE_REJECTED_STATUS (propagated)• DDS_DATA_ON_READERS_STATUS (propagated)• DDS_DATA_AVAILABLE_STATUS (propagated)• DDS_LIVELINESS_LOST_STATUS (propagated)• DDS_LIVELINESS_CHANGED_STATUS (propagated)• DDS_PUBLICATION_MATCHED_STATUS (propagated)• DDS_SUBSCRIPTION_MATCHED_STATUS (propagated).B e a wa r e t h a t t h e DDS_PUBLICATION_MATCHED_STATUS a n dDDS_SUBSCRIPTION_MATCHED_STATUS are not applicable when theinfrastructure does not have the information available to determine connectivity.This is the case when OpenSplice is configured not to maintain discoveryinformation in the Networking Service. (See also the description of theNetworkService/Discovery[@enabled] attribute in section 4.4.1.6.1on page 244 of the Deployment Guide.) In this case the operation will returnDDS_RETCODE_UNSUPPORTED.Status bits are declared as a constant and can be used by the application in an ORoperation to create a tailored mask. The special constant DDS_STATUS_MASK_NONEcan be used to indicate that the created entity should not respond to any of itsavailable statuses. The DDS will therefore attempt to propagate these statuses to its

213API Reference

3 DCPS Classes and Operations 3.2 Domain Module

factory. The special constant STATUS_MASK_ANY_V1_2 can be used to select allapplicable statuses specified in the “Data Distribution Service for Real-timeSystems Version 1.2” specification.

Status PropagationThe Data Distribution Service will trigger the most specific and relevant Listener.In other words, in case a communication status is also activated on the Listener ofa contained entity, the Listener on that contained entity is invoked instead of theDDS_DomainParticipantListener. This means that a status change on acontained entity only invokes the DDS_DomainParticipantListener if thecontained entity itself does not handle the trigger event generated by the statuschange.The s t a t u se s DDS_DATA_ON_READERS_STATUS a n d DDS_DATA_AVAILABLE_STATUS are “Read Communication Statuses” and are an exception toall other plain communication statuses: they have no corresponding status structurethat can be obtained with a get_<status_name>_status operation and they aremutually exclusive. When new information becomes available to a DataReader, theData Distribution Service will f irst look in an attached and activatedDDS_SubscriberListener or DDS_DomainParticipantListener (in thato r d e r ) f o r t h e DDS_DATA_ON_READERS_STATUS . I n c a s e t h eDDS_DATA_ON_READERS_STATUS can not be handled, the Data DistributionService will look in an attached and activated DDS_DataReaderListener,DDS_SubscriberListener or DDS_DomainParticipantListener for theDDS_DATA_AVAILABLE_STATUS (in that order).

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the DDS_DomainParticipantListener is attached.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_UNSUPPORTED - a status was selected that cannot be supported

because the infrastructure does not maintain the required connectivityinformation.

• DDS_RETCODE_ALREADY_DELETED - the DDS_DomainParticipant hasalready been deleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

214API Reference

3 DCPS Classes and Operations 3.2 Domain Module

3.2.1.39 DDS_DomainParticipant_set_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_set_qos (DDS_DomainParticipant _this, const DDS_DomainParticipantQos *qos);

DescriptionThis operation replaces the exist ing set of QosPolicy set t ings for aDDS_DomainParticipant.

Parametersin DDS_DomainParticipant _this - is the DDS_DomainParticipant object

on which the operation is operated.in const DDS_DomainParticipantQos *qos - must contain the new set of

QosPolicy settings for the DDS_DomainParticipant.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation replaces the exist ing set of QosPolicy set t ings for aDDS_DomainParticipant. The parameter qos must contain the struct with theQosPolicy settings which is checked for self-consistency.The set of QosPolicy settings specified by the qos parameter are applied on top ofthe existing QoS, replacing the values of any policies previously set (provided, theoperation returned DDS_RETCODE_OK).

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the new DDS_DomainParticipantQos is set.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.

215API Reference

3 DCPS Classes and Operations 3.2 Domain Module

• DDS_RETCODE_BAD_PARAMETER - the parameter qos is not a validDDS_DomainParticipantQos. It contains a QosPolicy setting with asequence that has inconsistent memory settings.

• DDS_RETCODE_ALREADY_DELETED - the DDS_DomainParticipant hasalready been deleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

3.2.1.40 DDS_DomainParticipant_delete_historical_data

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_delete_historical_data (DDS_DomainParticipant _this, const DDS_string partition_expression, const DDS_string topic_expression);

DescriptionThis operation deletes all historical TRANSIENT and PERSISTENT data that isstored by the durability service that is configured to support this DomainParticipant.

Parametersin DDS_DomainParticipant _this - is the DDS_DomainParticipant

object on which the operation is operated.in const DDS_string partition_expression - An expression to define a

filter on partitions.in const DDS_string topic_expression - An expression to define a filter

on topic names.

Return ValueDDS_ReturnCode_t - Poss ib le re turn codes of the opera t ion are :

DDS_RETCODE_OK, DDS_RETCODE_ERROR.

Detailed DescriptionThis operation deletes all historical TRANSIENT and PERSISTENT data that isstored by the durability service that is configured to support this DomainParticipant.It only deletes the samples stored in the transient and persistent store, samples storedin individual application DataReaders is spared and remains available to thesereaders. However, late-joiners will no longer be able to obtain the deleted samples.

216API Reference

3 DCPS Classes and Operations 3.2 Domain Module

The partition_expression and topic_expression strings can be used tospecify selection criteria for the topic and/or partition in which the data will bedeleted. Wildcards are supported. Note that these parameters are mandatory andcannot be empty. The "*" expression can be used to match all partitions and/ortopics.Only data that exists prior to this method invocationis deleted. Data that is still beinginserted during this method invocationwill not be removed.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - all data matching the topic and partition expressions has

been deleted.• DDS_RETCODE_ERROR - an internal error has occurred.

3.2.1.41 DDS_DomainParticipant_get_property

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_get_property (DDS_DomainParticipant this, DDS_DomainParticipantProperty *a_property);

DescriptionThis function queries the value of a property set on a DDS_DomainParticipant.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant object

on which the operation is operated.in DDS_DomainParticipantProperty *a_property - on entry,

a_property.name determines which property to query the value of; onsuccessful return, a_property.value is set to the current value of thatproperty in the DDS_DomainParticipant.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_ERROR,DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES orDDS_RETCODE_UNSUPPORTED.

217API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Detailed DescriptionThis operation looks up the property specified by a_property.name in theDDS_DomainParticipant, setting a_property.value to the current value ofthe property. If the property has not been set using set_property, the defaultvalue is returned.NOTE: The user application is responsible for freeing the memory that is allocatedby the middleware for a_property.value.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - a_property.value has been set to the current value of

the property.• DDS_RETCODE_BAD_PARAMETER - an invalid value has been specified.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ALREADY_DELETED - the DDS_DomainParticipant has

already been deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_UNSUPPORTED - a_property.name specifies an undefined

property or the operation is not supported in this version.

3.2.1.42 DDS_DomainParticipant_set_property

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipant_set_property (DDS_DomainParticipant this, const DDS_DomainParticipantProperty *a_property);

DescriptionThis function sets a property on a DDS_DomainParticipant.

Parametersin DDS_DomainParticipant _this - the DDS_DomainParticipant object

on which the operation is operated.in DDS_DomainParticipantProperty a_property - on specifies the

property (in a_property.name) and its new value (in a_property.value).

218API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_ERROR,DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES orDDS_RETCODE_UNSUPPORTED.

Detailed DescriptionThis operation sets the property specified by a_property.name to the value givenby a_property.value.Currently, the following properties are defined:

isolateNodeThe isolateNode property allows applications to isolate the federation from therest of the Domain; i.e. at network level to disconnect the node from the rest of thesystem.Applications also need to be able to issue a request to re-connect their federation tothe domain again, after which the durability merge-policy that is configured needsto be applied.To isolate a federation, the application needs to set the isolateNode propertyvalue to ‘true’, and to (de)isolate the federation the same property needs to be setto ‘false’. The default value of the isolateNode property is ‘false’.All data that is published after isolateNode is set to true will not be sent to thenetwork, and any data received from the network will be ignored.Be aware that data being processed by the network service at the time of isolating anode may still be sent to the network, due to the asynchronous nature of networkservice internals.The value is interpreted as a boolean (i.e., it must be either ‘true’ or ‘false’).• false (default): The federation is connected to the domain.• true: The federation is disconnected from the domain meaning that data is not

published on the network and data from the network is ignored.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the property has been set.• DDS_RETCODE_BAD_PARAMETER - an invalid value has been specified.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ALREADY_DELETED - the DDS_DomainParticipant has

already been deleted.

219

API Reference

3 DCPS Classes and Operations 3.2 Domain Module

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_UNSUPPORTED - a_property.name specifies an undefinedproperty or the operation is not supported in this version.

3.2.2 Class DDS_DomainParticipantFactoryThe purpose of this class is to al low the creat ion and destruct ion ofDDS_DomainParticipant objects. DDS_DomainParticipantFactory itselfhas no factory. It is a pre-existing singleton object that can be accessed by means ofthe DDS_DomainParticipantFactory_get_instance operation on theDDS_DomainParticipantFactory class.The pre-defined value DDS_TheParticipantFactory can also be used as ana l i a s f o r t h e s i n g l e t o n f a c t o ry r e t u r n e d b y t h e o p e r a t i o nDDS_DomainParticipantFactory_get_instance.The interface description of this class is as follows:

/* * interface DDS_DomainParticipantFactory *//* * implemented API operations */

DDS_DomainParticipantFactory DDS_DomainParticipantFactory_get_instance (void);DDS_DomainParticipant DDS_DomainParticipantFactory_create_participant (DDS_DomainParticipantFactory _this,

const DomainId_t domainId, const DDS_DomainParticipantQos *qos, const struct DDS_DomainParticipantListener *a_listener, const DDS_StatusMask mask);

DDS_ReturnCode_t DDS_DomainParticipantFactory_delete_participant (DDS_DomainParticipantFactory _this, const DDS_DomainParticipant a_participant);DDS_DomainParticipant DDS_DomainParticipantFactory_lookup_participant (DDS_DomainParticipantFactory _this, const DomainId_t domainId);DDS_ReturnCode_t DDS_DomainParticipantFactory_set_default_participant_qos (DDS_DomainParticipantFactory _this, const DDS_DomainParticipantQos *qos);DDS_ReturnCode_t DDS_DomainParticipantFactory_get_default_participant_qos

220API Reference

3 DCPS Classes and Operations 3.2 Domain Module

(DDS_DomainParticipantFactory _this, DDS_DomainParticipantQos *qos);DDS_ReturnCode_t DDS_DomainParticipantFactory_set_qos (DDS_DomainParticipantFactory _this, const DDS_DomainParticipantFactoryQos *qos);DDS_ReturnCode_t DDS_DomainParticipantFactory_get_qos (DDS_DomainParticipantFactory _this, DDS_DomainParticipantFactoryQos *qos);DDS_ReturnCode_t DDS_DomainParticipantFactory_delete_domain (DDS_DomainParticipantFactory _this, DDS_Domain a_domain);DDS_Domain DDS_DomainParticipantFactory_lookup_domain (DDS_DomainParticipantFactory _this, const DomainId_t domainId);DDS_ReturnCode_t

DDS_DomainParticipantFactory_delete_contained_entities(DDS_DomainParticipantFactory _this);

DDS_ReturnCode_tDDS_DomainParticipantFactory_detach_all_domains (DDS_DomainParticipantFactory _this, DDS_boolean block_operations, DDS_boolean delete_entities);

T h e f o l l o w i n g p a r a g r a ph s d e s c r i b e t h e u s a g e o f a l lDDS_DomainParticipantFactory operations.

3.2.2.1 DDS_DomainParticipantFactory_create_participant

Synopsis#include <dds_dcps.h>DDS_DomainParticipant DDS_DomainParticipantFactory_create_participant (DDS_DomainParticipantFactory _this, const DomainId_t domainId, const DDS_DomainParticipantQos *qos, const struct DDS_DomainParticipantListener *a_listener, const DDS_StatusMask mask);

DescriptionThis operation creates a new DDS_DomainParticipant which will join thedomain identified by domainId, with the desired DDS_DomainParticipantQosand attaches the optionally specified DDS_DomainParticipantListener to it.

221API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Parametersin DDS_DomainParticipantFactory _this - t h e

DDS_DomainParticipantFactory object on which the operation isoperated.

in const DomainId_t domainId - the ID of the Domain to which theDDS_DomainParticipant is joined. This should be the ID as specified in theconfiguration file. This will also be applicable for the lookup_participant,lookup_domain and get_domain_id operations.

in const DDS_DomainParticipantQos *qos - aDDS_DomainParticipantQos for the new DDS_DomainParticipant.W h e n t h i s s e t o f QosPolicy s e t t i n g s i s i n c o n s i s t e n t , n oDDS_DomainParticipant is created.

in const struct DDS_DomainParticipantListener *a_listener - apointer to the DDS_DomainParticipantListener instance which will beattached to the new DDS_DomainParticipant. It is permitted to useDDS_OBJECT_NIL as the value of the l i s tener : this behaves as aDDS_DomainParticipantListener whose operations perform no action.

in const DDS_StatusMask mask - a bit-mask in which each bit enables theinvocation of the DDS_DomainParticipantListener for a certain status.

Return ValueDDS_DomainParticipant -Return value is a pointer to the newly-created

DDS_DomainParticipant. In case of an error, the DDS_OBJECT_NIL pointeris returned.

Detailed DescriptionThis operation creates a new DDS_DomainParticipant, with the desiredDDS_DomainParticipantQos and attaches the optionally specifiedDDS_DomainParticipantListener to it. The DDS_DomainParticipantsignifies that the calling application intends to join the Domain identified by thedomainId argument.If the specified QosPolicy settings are not consistent, the operation will fail; noDDS_DomainParticipant i s created and the operat ion re turns theDDS_OBJECT_NIL pointer. To delete the DDS_DomainParticipant the operationDDS_DomainParticipantFactory_delete_participant must be used.

222API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Identifying the DomainThe DDS_DomainParticipant will attach to the Domain that is specified by thedomainId parameter. This parameter corresponds to the integer specified in the Idtag in the configuration file. Note that to make multiple connections to a Domain(create multiple Participants for the same Domain) within a single process, all of theParticipants must use the same identification (i.e. all use the same domain Id). The constant DDS_DOMAIN_ID_DEFAULT can be used for this parameter. If this isdone the value of Id tag from the configuration file specified by the environmentvariable called OSPL_URI will be used.It is recommended to use this domain Id in conjunction with the OSPL_URIenvironment variable instead of hard-coding a domain Id into your application,since this gives you much more flexibility in the deployment phase of your product.See also Section 1.3.2.1, The OSPL_URI environment variable, in the DeploymentGuide.

Default QoSThe constant DDS_PARTICIPANT_QOS_DEFAULT can be used as parameter qos toc r ea t e a DDS_DomainParticipant w i t h t h e d e f a u l tDDS_DomainParticipantQos a s s e t i n t h eDDS_DomainParticipantfactory. T h e e ff e c t o f u s i n gDDS_PARTICIPANT_QOS_DEFAULT is the same as calling the operationDDS_DomainParticipantFactory_get_default_participant_qos andu s i n g th e r e s u l t i n g DDS_DomainParticipantQos t o c r e a t e t h eDDS_DomainParticipant.

Communication StatusFor each communication status, the StatusChangedFlag flag is initially set toFALSE. It becomes TRUE whenever that communication status changes. For eachcommun ica t i on s t a t u s a c t i va t ed i n t he mask , t h e a s soc i a t e dDDS_DomainParticipantListener opera t ion i s invoked and thecommunication status is reset to FALSE, as the listener implicitly accesses the statuswhich is passed as a parameter to that operation. The fact that the status is reset priort o c a l l i n g t h e l i s t e n e r m e a n s t ha t i f t h e a p p l i c a t i o n c a l l s t h eget_<status_name>_status from inside the listener it will see the statusalready reset. The following statuses are applicable to the DDS_DomainParticipantListener:• DDS_INCONSISTENT_TOPIC_STATUS (propagated)• DDS_OFFERED_DEADLINE_MISSED_STATUS (propagated)• DDS_REQUESTED_DEADLINE_MISSED_STATUS (propagated)

223API Reference

3 DCPS Classes and Operations 3.2 Domain Module

• DDS_OFFERED_INCOMPATIBLE_QOS_STATUS (propagated)• DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS (propagated)• DDS_SAMPLE_LOST_STATUS (propagated)• DDS_SAMPLE_REJECTED_STATUS (propagated)• DDS_DATA_ON_READERS_STATUS (propagated)• DDS_DATA_AVAILABLE_STATUS (propagated)• DDS_LIVELINESS_LOST_STATUS (propagated)• DDS_LIVELINESS_CHANGED_STATUS (propagated)• DDS_PUBLICATION_MATCHED_STATUS (propagated)• DDS_SUBSCRIPTION_MATCHED_STATUS (propagated).B e a wa r e t h a t t h e DDS_PUBLICATION_MATCHED_STATUS a n dDDS_SUBSCRIPTION_MATCHED_STATUS are not applicable when theinfrastructure does not have the information available to determine connectivity.This is the case when OpenSplice is configured not to maintain discoveryinformation in the Networking Service. (See also the description of theNetworkService/Discovery[@enabled] attribute in section 4.4.1.6.1on page 244 of the Deployment Guide.) In this case the operation will returnDDS_OBJECT_NIL.Status bits are declared as a constant and can be used by the application in an ORoperation to create a tailored mask. The special constant DDS_STATUS_MASK_NONEcan be used to indicate that the created entity should not respond to any of itsavailable statuses. The DDS will therefore attempt to propagate these statuses to itsfactory. The special constant STATUS_MASK_ANY_V1_2 can be used to select allapplicable statuses specified in the “Data Distribution Service for Real-timeSystems Version 1.2” specification.

Status PropagationThe Data Distribution Service will trigger the most specific and relevant Listener.In other words, in case a communication status is also activated on the Listener ofa contained entity, the Listener on that contained entity is invoked instead of theDDS_DomainParticipantListener. This means that a status change on acontained entity only invokes the DDS_DomainParticipantListener if thecontained entity itself does not handle the trigger event generated by the statuschange.The s t a t u se s DDS_DATA_ON_READERS_STATUS a n d DDS_DATA_AVAILABLE_STATUS are “Read Communication Statuses” and are an exception toall other plain communication statuses: they have no corresponding status structurethat can be obtained with a get_<status_name>_status operation and they are

224API Reference

3 DCPS Classes and Operations 3.2 Domain Module

mutually exclusive. When new information becomes available to a DataReader, theData Distribution Service will f irst look in an attached and activatedDDS_SubscriberListener or DDS_DomainParticipantListener (in thato r d e r ) f o r t h e DDS_DATA_ON_READERS_STATUS . I n c a s e t h eDDS_DATA_ON_READERS_STATUS can not be handled, the Data DistributionService will look in an attached and activated DDS_DataReaderListener,DDS_SubscriberListener or DDS_DomainParticipantListener for theDDS_DATA_AVAILABLE_STATUS (in that order).

3.2.2.2 DDS_DomainParticipantFactory_delete_participant

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipantFactory_delete_participant (DDS_DomainParticipantFactory _this, const DDS_DomainParticipant a_participant);

DescriptionThis operation deletes a DDS_DomainParticipant.

Parametersin DDS_DomainParticipantFactory _this - t h e

DDS_DomainParticipantFactory object on which the operation isoperated.

in const DDS_DomainParticipant a_participant - a pointer to theDDS_DomainParticipant, which is to be deleted.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_ PRECONDITION_NOT_MET.

Detailed DescriptionT h i s o p e r a t i o n d e l e t e s a DDS_DomainParticipant . ADDS_DomainParticipant cannot be deleted when it has any attachedDDS_Entity ob j e c t s . When t he op e r a t i o n i s c a l l ed on aDDS_DomainParticipant with existing DDS_Entity objects, the operationreturns DDS_RETCODE_PRECONDITION_NOT_MET.

225API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the DDS_DomainParticipant is deleted.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter a_participant is not a validDDS_DomainParticipant.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_PRECONDITION_NOT_MET - the DDS_DomainParticipantcontains one or more DDS_Entity objects.

3.2.2.3 DDS_DomainParticipantFactory_get_default_participant_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipantFactory_get_default_participant_qos (DDS_DomainParticipantFactory _this, DDS_DomainParticipantQos *qos);

DescriptionThis operation gets the default DDS_DomainParticipantQos of theDDS_DomainParticipant.

Parametersin DDS_DomainParticipantFactory _this - t h e

DDS_DomainParticipantFactory object on which the operation isoperated.

inout DDS_DomainParticipantQos *qos - a po i n t e r t o t heDDS_DomainParticipantQos struct (provided by the application) in whicht he d e f a u l t DDS_DomainParticipantQos f o r t h eDDS_DomainParticipant is written.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION or DDS_RETCODE_OUT_OF_RESOURCES.

226API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Detailed DescriptionThis operation gets the default DDS_DomainParticipantQos of theDDS_DomainParticipant (that is the struct with the QosPolicy settings) whichis used for newly-created DDS_DomainParticipant objects, in case the constantDDS_PARTICIPANT_QOS_DEFAULT i s u s ed . The de f au l tDDS_DomainParticipantQos is only used when the constant is supplied asparameter qos to specify the DDS_DomainParticipantQos in theDDS_DomainParticipantFactory_create_participant operation. Theapplication must provide the DDS_DomainParticipantQos struct in which theQosPolicy settings can be stored and provide a pointer to the struct. The operationwrites the default QosPolicy settings to the struct pointed to by qos. Any settingsin the struct are overwritten.The values retrieved by this operation match the set of values specified on the lastsuccessful call to DDS_DomainParticipantFactory_set_default_participant_qos, or, if the call was never made, the default values as specifiedfor each QosPolicy setting as defined in Table 5: on page 65.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the default DDS_DomainParticipant QosPolicy settings

of this DDS_DomainParticipantFactory have successfully been copied intothe specified DDS_DomainParticipantQos parameter.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

3.2.2.4 DDS_DomainParticipantFactory_get_instance

Synopsis#include <dds_dcps.h>DDS_DomainParticipantFactory DDS_DomainParticipantFactory_get_instance (void);

DescriptionThis operation returns the DDS_DomainParticipantFactory singleton.

Parameters<none>

227API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Return ValueDDS_DomainParticipantFactory - return value is a pointer to the

DDS_DomainParticipantFactory.

Detailed DescriptionThis operation returns the DDS_DomainParticipantFactory singleton. Theoperation can be called multiple times without side-effects and it returns the sameDDS_DomainParticipantFactory instance.The pre-defined value DDS_TheParticipantFactory can also be used as ana l i a s f o r t h e s i n g l e t o n f a c t o ry r e t u r n e d b y t h e o p e r a t i o nDDS_DomainParticipantFactory_get_instance.

3.2.2.5 DDS_DomainParticipantFactory_get_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipantFactory_get_qos (DDS_DomainParticipantFactory _this, DDS_DomainParticipantFactoryQos *qos);

DescriptionThis operation allows access to the existing set of QoS policies for aDDS_DomainParticipantFactory.

Parametersin DDS_DomainParticipantFactory _this - t h e

DDS_DomainParticipantFactory object on which the operation isoperated.

inout DDS_DomainParticipantFactoryQos *qos - a pointer to thedestination DDS_DomainparticipantFactoryQos struct in which theQosPolicy settings will be copied.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION or DDS_RETCODE_ OUT_OF_RESOURCES.

228API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Detailed DescriptionThis operation al lows access to the exist ing set of QoS policies of aDDS_DomainParticipantFactory on which this operation is used. ThisDDS_DomainparticipantFactoryQos is stored at the location pointed to by theqos parameter.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the existing set of QoS policy values applied to thisDDS_DomainParticipantFactory has successfully been copied into thespecified DDS_DomainParticipantFactoryQos parameter.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

3.2.2.6 DDS_DomainParticipantFactory_lookup_participant

Synopsis#include <dds_dcps.h>DDS_DomainParticipant DDS_DomainParticipantFactory_lookup_participant (DDS_DomainParticipantFactory _this, const DomainId_t domainId);

DescriptionThis operation retrieves a previously created DDS_DomainParticipantbelonging to the specified domainId.

Parametersin DDS_DomainParticipantFactory _this - t h e

DDS_DomainParticipantFactory object on which the operation isoperated.

in const DomainId_t domainId - the ID of the Domain for which a joiningDDS_DomainParticipant should be retrieved. This should be the ID asspecified in the configuration file.

229API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Return ValueDDS_DomainParticipant - R e tu r n v a l u e i s a p o in t e r t o t h e

DDS_DomainParticipant r e t r i e v e d . W he n n o s uc hDDS_DomainParticipant is found, the DDS_OBJECT_NIL pointer isreturned.

Detailed DescriptionThis operation retrieves a previously created DDS_DomainParticipantbelonging to the specified domainId. If no such DDS_DomainParticipantexists, the operation will return DDS_OBJECT_NIL.The domainId used to search for a specific DDS_DomainParticipant must bei d e n t i c a l t o t h e domainId t h a t w a s u s e d t o c r e a t e t h a t s p e c i f i cDDS_DomainParticipant.If multiple DDS_DomainParticipant entities belonging to the specifieddomainId exist, then the operation will return one of them. It is not specified whichone. See also DDS_DomainParticipantFactory_create_participant (section 3.2.2.1on page 221).

3.2.2.7 DDS_DomainParticipantFactory_set_default_participant_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipantFactory_set_default_participant_qos (DDS_DomainParticipantFactory _this, const DDS_DomainParticipantQos *qos);

DescriptionThis operation sets the default DDS_DomainParticipantQos of theDDS_DomainParticipant.

Parametersin DDS_DomainParticipantFactory _this - t h e

DDS_DomainParticipantFactory object on which the operation isoperated.

in const DDS_DomainParticipantQos *qos - t h eDDS_DomainParticipantQos struct, which contains the new defaultDDS_DomainParticipantQos f o r t h e n e w l y - c r e a t e dDDS_DomainParticipants.

230API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation sets the default DDS_DomainParticipantQos of theDDS_DomainParticipant (that is the struct with the QosPolicy settings) whichis used for newly-created DDS_DomainParticipant objects, in case the constantDDS_PARTICIPANT_QOS_DEFAULT i s u s ed . The de f au l tDDS_DomainParticipantQos is only used when the constant is supplied asparameter qos to specify the DDS_DomainParticipantQos in theDDS_DomainParticipantFactory_create_participant operation. TheDDS_DomainParticipantQos is always self consistent, because its policies donot depend on each other. This means this operation never returns theDDS_RETCODE_INCONSISTENT_POLICY.T h e v a l u e s s e t b y t h i s o p e r a t i o n a r e r e t u r n e d b yDDS_DomainParticipantFactory_get_default_participant_qos.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the new default DDS_DomainParticipantQos is set.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter qos is not a validDDS_DomainParticipantQos. It contains a QosPolicy setting with asequence that has inconsistent memory settings.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

3.2.2.8 DDS_DomainParticipantFactory_set_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DomainParticipantFactory_set_qos (DDS_DomainParticipantFactory _this, const DDS_DomainParticipantFactoryQos *qos);

231API Reference

3 DCPS Classes and Operations 3.2 Domain Module

DescriptionThis operation replaces the exist ing set of QosPolicy set t ings for aDDS_DomainParticipantFactory.

Parametersin DDS_DomainParticipantFactory _this - i s t h e

DDS_DomainParticipantFactory object on which the operation isoperated.

in const DDS_DomainParticipantFactoryQos *qos - must contain thenew set of QosPolicy settings for the DDS_DomainParticipantFactory.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation replaces the exist ing set of QosPolicy set t ings for aDDS_DomainParticipantFactory. The parameter qos must contain the structwith the QosPolicy settings.The set of QosPolicy settings specified by the qos parameter are applied on top ofthe existing QoS, replacing the values of any policies previously set (provided, theoperation returned DDS_RETCODE_OK).

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the new DDS_DomainParticipantFactoryQos is set.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

3.2.2.9 DDS_DomainParticipantFactory_delete_domain

Synopsis#include <dds_dcps.h> DDS_ReturnCode_t DDS_DomainParticipantFactory_delete_domain (DDS_DomainParticipantFactory _this,

232API Reference

3 DCPS Classes and Operations 3.2 Domain Module

DDS_Domain a_domain);

DescriptionThis operation deletes a DDS_Domain.

Parametersin DDS_DomainParticipantFactory _this -

the DDS_DomainParticipantFactory object on which the operation isoperated.

in DDS_Domain a_domain - a pointer to the DDS_Domain, which is to bedeleted.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation deletes a DDS_Domain.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the DDS_Domain is deleted.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter a_domain is not a validDDS_Domain.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

3.2.2.10 DDS_DomainParticipantFactory_lookup_domain

Synopsis#include <dds_dcps.h> DDS_Domain DDS_DomainParticipantFactory_lookup_domain (DDS_DomainParticipantFactory _this, const DomainId_t domainId);

233API Reference

3 DCPS Classes and Operations 3.2 Domain Module

DescriptionThis operation retrieves a previously created DDS_Domain proxy belonging to thespecified domainId or creates a new DDS_Domain if no DDS_Domain yet existsbut the Domain itself is available.

Parametersin DDS_DomainParticipantFactory _this -

the DDS_DomainParticipantFactory object on which the operation isoperated.

in const DomainId_t domainId - the ID of the Domain for which aDDS_Domain proxy should be retrieved. This should be the ID as specified inthe configuration file.

Return ValueDDS_Domain - Return value is a pointer to the DDS_Domain proxy retrieved. When

n o s u c h DDS_Domain p ro xy i s f o un d o r c o u l d b e c r e a t e d , t h eDDS_OBJECT_NIL pointer is returned.

Detailed DescriptionThis operation retrieves a previously created DDS_Domain proxy belonging to thespecified domainId or creates a new DDS_Domain proxy if no DDS_Domain proxywas found, but the DomainId does refer to a valid Domain. If no such DDS_Domainexists or could be created, the operation will return DDS_OBJECT_NIL. See alsoDDS_DomainParticipantFactory_create_participant (section 3.2.2.1 on page 221).

3.2.2.11 DDS_DomainParticipantFactory_delete_contained_entities

Synopsis#include <dds_dcps.h>

DDS_ReturnCode_tDDS_DomainParticipantFactory_delete_contained_entities

(DDS_DomainParticipantFactory _this);

DescriptionThis operation deletes all of the DDS_Entity objects that were created on theDDS_DomainParticipantFactory.

Parametersin DDS_DomainParticipantFactory _this -

the DDS_DomainParticipantFactory object on which the operation isperformed.

234API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Return ValueDDS_ReturnCode_t - Possible return codes of the operation are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_OUT_OF_RESOURCES , DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_BAD_PARAMETER.

Detailed DescriptionThis operation deletes all of the DDS_Entity objects that were created on theDDS_DomainParticipantFactory ( i t d e l e t e s a l l con t a ine dDDS_DomainParticipant objects). Prior to deleting each containedDDS_Entity, t h i s o p e r a t i o n r e g r e s s i v e l y c a l l s t h eDDS_DomainParticipant_delete_contained_entities operation on eachDDS_Participant. In other words, this operation cleans up all DDS_Entityobjects in the process.

NOTE: The operation will return DDS_PRECONDITION_NOT_MET if the any of thecontained entities is in a state where it cannot be deleted. This will occur, forexample, if a contained DDS_DataReader cannot be deleted because theapplication has called a read or take operation and has not called thecorresponding return_loan operation to return the loaned samples. In such cases,the operation does not roll back any entity deletions performed prior to the detectionof the problem.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - all contained DDS_Entity objects are deleted.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_PRECONDITION_NOT_MET - one or more of the contained entities

are in a state where they cannot be deleted.• DDS_RETCODE_BAD_PARAMETER - the parameter _this is not a validDDS_DomainParticipantFactory.

3.2.2.12 DDS_DomainParticipantFactory_detach_all_domains

Synopsis#include <dds_dcps.h>

235API Reference

3 DCPS Classes and Operations 3.2 Domain Module

DDS_ReturnCode_t DDS_DomainParticipantFactory_detach_all_domains (DDS_DomainParticipantFactory _this, DDS_boolean block_operations, DDS_boolean delete_entities);

DescriptionThis operation will safely detach the application from all domains it is currentlyparticipating in.

Parametersin DDS_DomainParticipantFactory _this –

The DDS_DomainParticipantFactory object on which the operation isperformed.

in DDS_boolean block_operations –Indicates whether the application wants any operations that are called whiledetaching to be blocked or not.

in DDS_boolean delete_entities –Indicates whether the application DDS entities in the ‘connected’ domains mustbe deleted synchronously during detaching.

Return ValueDDS_ReturnCode_t - Possible return codes of the operation are:

DDS_RETCODE_OK

Detailed DescriptionThis operation safely detaches the application from all domains it is currentlyparticipating in. When this operation has been performed successfully, theapplication is no longer connected to any Domain.• For Federated domains, finishing this operation successfully means that all shared

memory segments have been safely un-mapped from the application process.• For SingleProcess mode domains, this means all services for all domains have

been stopped. This allows graceful termination of the OSPL services that run asthreads within the application. Graceful termination of services in this modewould for instance allow durability flushing of persistent data and networkingtermination announcement over the network.

When this call returns, further access to all domains will be denied and it will not bepossible for the application to open or re-open any DDS domain.The behavior of the detach_all_domains operation is determined by theblock_operations and delete_entities parameters

236API Reference

3 DCPS Classes and Operations 3.2 Domain Module

block_operations – This parameter specifies whether the application wants anyDDS operation to be blocked or not while detaching. When TRUE, any DDSoperation called during this operation will be blocked and remain blockedforever (so also after the detach operation has completed and returns to thecaller). When FALSE, any DDS operation called during this operation mayreturn DDS_RETCODE_ALREADY_DELETED.Please note that a listener callback is not considered an operation in progress. Ofcourse, if a DDS operation is called from within the listener callback, thatoperation will be blocked during the detaching if this attribute is set to TRUE.

delete_entities – This parameter specifies whether the application wants theDDS entities created by the application to be deleted (synchronously) whiledetaching from the domain or not. If TRUE, all application entities areguaranteed to be deleted when the call returns. If FALSE, application entitieswill not explicitly be deleted by this operation. In federated mode, the splice-daemon will delete them asynchronously after thisoperation has returned successfully. In SingleProcess mode this attribute isignored and clean up will always be performed, as this cannot be delegated to adifferent process.

NOTE: In federated mode when the detach_all_domain operation is called withblock_operations set to FALSE and delete_entities also FALSE then theDDS operations which are in progress and which are waiting for some condition tobecome true (or waiting for an event to occur) while the detach operation isperformed may be blocked.

Return CodeWhen the operation returns:• DDS_RETCODE_OK – the application is detached from all domains.

3.2.3 Class DDS_DomainThe purpose of this class is to represent the Domain and allow certain Domain-wideoperations to be performed. In essence it is a proxy to the Domain.A Domain is a distributed concept that links all the applications that must be able tocommunicate with each other. It represents a communication plane: only theDDS_Publishers and the DDS_Subscribers attached to the same Domain caninteract.This class currently implements one function:• It allows for a snapshot to be taken of all persistent data available within thisDomain on local node level.

The interface description of this class is as follows:/*

237API Reference

3 DCPS Classes and Operations 3.2 Domain Module

* interface DDS_Domain*/DDS_ReturnCode_t DDS_Domain_create_persistent_snapshot( DDS_Domain _this, const DDS_char* partition_expression, const DDS_char* topic_expression, const DDS_char* URI);

The following sections describe the usage of all DDS_Domain operations.

3.2.3.1 DDS_Domain_create_persistent_snapshot

Synopsis#include <dds_dcps.h> DDS_ReturnCode_t DDS_Domain_create_persistent_snapshot( DDS_Domain _this, const DDS_char* partition_expression, const DDS_char* topic_expression, const DDS_char* URI);

DescriptionThis operation will create a snapshot of all persistent data matching the providedpartition and topic expressions and store the snapshot at the location indicated bythe URI. Only persistent data available on the local node is considered.

Parametersin DDS_Domain _this - the DDS_Domain object on which the operation is

operated.in DDS_char* partition_expression - the expression of all partitions

involved in the snapshot; this may contain wildcards.in DDS_char* topic_expression - the expression of all topics involved in the

snapshot; this may contain wildcards.in DDS_char* uri - the location where to store the snapshot. Currently only

directories are supported.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

238API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Detailed DescriptionThis operation will create a snapshot of all persistent data matching the providedpartition and topic expressions and store the snapshot at the location indicated bythe URI. Only persistent data available on the local node is considered. Thisoperation will fire an event to trigger the snapshot creation by the durability serviceand then return while the durability service fulfills the snapshot request; if nodurability service is available then there is no persistent data available and theoperation will return OK as a snapshot of an empty store is an empty store.The created snapshot can then be used as the persistent store for the durabilityservice next time it starts up by configuring the location of the snapshot as thepersistent store in the configuration file. The durability service will then use thesnapshot as the regular store (and can thus also alter its contents).

Return CodeWhen the operation returns:• DDS_RETCODE_OK – The persistent snapshot is (being) created.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter partition_expression,topic_expression or uri is NIL.

• DDS_RETCODE_ALREADY_DELETED - the DDS_Domain proxy has already beendeleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

3.2.4 DDS_DomainParticipantListener interfaceSince a DDS_DomainParticipant is a DDS_Entity, it has the ability to have aListener associated with it. In this case, the associated Listener should be oftype DDS_DomainParticipantListener. This interface must be implementedby the application. A user-defined class must be provided by the application whichmust extend from the DDS_DomainParticipantListener class. AllDDS_DomainParticipantListener operations must be implemented in theuser-defined class, it is up to the application whether an operation is empty orcontains some functionality.

All operations for this interface must be implemented in the user-defined class, it isup to the application whether an operation is empty or contains some functionality.

239API Reference

3 DCPS Classes and Operations 3.2 Domain Module

The DDS_DomainParticipantListener provides a generic mechanism(actually a callback function) for the Data Distribution Service to notify theapplication of relevant asynchronous status change events, such as a missedd e a d l i n e , v i o l a t i o n o f a QosPolicy s e t t i n g , e t c . T h eDDS_DomainParticipantListener is related to changes in communicationstatus DDS_StatusConditions.The interface description of this class is as follows:

/* * interface DDS_DomainParticipantListener *//* * inherited from DDS_TopicListener *//* void * DDS_DomainParticipantListener_on_inconsistent_topic * (void *listener_data, * DDS_Topic the_topic, * const DDS_InconsistentTopicStatus *status); *//* * inherited from DDS_PublisherListener *//* void * DDS_DomainParticipantListener_on_offered_deadline_missed * (void *listener_data, * DDS_DataWriter writer, * const DDS_OfferedDeadlineMissedStatus *status); */

/* void * DDS_DomainParticipantListener_on_offered_incompatible_qos * (void *listener_data, * DDS_DataWriter writer, * const DDS_OfferedIncompatibleQosStatus *status); */

/* void * DDS_DomainParticipantListener_on_liveliness_lost * (void *listener_data, * DDS_DataWriter writer, * const DDS_LivelinessLostStatus *status); */

/* void * DDS_DomainParticipantListener_on_publication_matched * (void *listener_data, * DDS_DataWriter writer, * const DDS_PublicationMatchedStatus *status);

240API Reference

3 DCPS Classes and Operations 3.2 Domain Module

*//* * inherited from DDS_SubscriberListener *//* void * DDS_DomainParticipantListener_on_data_on_readers * (void *listener_data, * DDS_Subscriber subs); *//* void

* DDS_DomainParticipantListener_on_requested_deadline_missed * (void *listener_data, * DDS_DataReader reader, * const DDS_RequestedDeadlineMissedStatus *status); */

/* void * DDS_DomainParticipantListener_on_requested_incompatible_qos * (void *listener_data, * DDS_DataReader reader, * const DDS_RequestedIncompatibleQosStatus *status); */

/* void * DDS_DomainParticipantListener_on_sample_rejected * (void *listener_data, * DDS_DataReader reader, * const DDS_SampleRejectedStatus *status); */

/* void * DDS_DomainParticipantListener_on_liveliness_changed * (void *listener_data, * DDS_DataReader reader, * const DDS_LivelinessChangedStatus *status); */

/* void * DDS_DomainParticipantListener_on_data_available * (void *listener_data, * DDS_DataReader reader); */

/* void * DDS_DomainParticipantListener_on_subscription_matched * (void *listener_data, * DDS_DataReader reader, * const DDS_SubscriptionMatchedStatus *status); */

241API Reference

3 DCPS Classes and Operations 3.2 Domain Module

/* void * DDS_DomainParticipantListener_on_sample_lost * (void *listener_data, * DDS_DataReader reader, * const DDS_SampleLostStatus *status); *//* * implemented API operations */

struct DDS_DomainParticipantListener * DDS_DomainParticipantListener__alloc (void);

The next paragraphs list all DDS_DomainParticipantListener operations.Since these operations are all inherited, they are listed but not fully describedbecause they are not implemented in this class. The full description of theseoperations is given in the classes from which they are inherited.

3.2.4.1 DDS_DomainParticipantListener__alloc

Synopsis#include <dds_dcps.h>struct DDS_DomainParticipantListener * DDS_DomainParticipantListener__alloc (void);

DescriptionThis operation creates a new DDS_DomainParticipantListener.

Parameters<none>

Return Valuestruct DDS_DomainParticipantListener * - Return value is the handle to

the newly-created DDS_DomainParticipantListener. In case of an error, aDDS_OBJECT_NIL pointer is returned.

Detailed DescriptionThis operation creates a new DDS_DomainParticipantListener. TheDDS_DomainParticipantListener must be created using this operation. Inother words, the application is not allowed to declare an object of typeDDS_DomainParticipantListener. When the application wants to release theDDS_DomainParticipantListener it must be released using DDS_free.

242API Reference

3 DCPS Classes and Operations 3.2 Domain Module

I n c a s e t h e r e a r e i n s u ff i c i e n t r e s o u r c e s a v a i l a b l e t o a l l o c a t e t h eDDS_DomainParticipantListener, a DDS_OBJECT_NIL pointer is returnedinstead.

3.2.4.2 DDS_DomainParticipantListener_on_data_available (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_DataReaderListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_DomainParticipantListener_on_data_available (void *listener_data, DDS_DataReader reader);

3.2.4.3 DDS_DomainParticipantListener_on_data_on_readers (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_SubscriberListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_DomainParticipantListener_on_data_on_readers (void *listener_data, DDS_Subscriber subs);

3.2.4.4 DDS_DomainParticipantListener_on_inconsistent_topic (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_TopicListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_DomainParticipantListener_on_inconsistent_topic (void *listener_data, DDS_Topic the_topic, const DDS_InconsistentTopicStatus *status);

3.2.4.5 DDS_DomainParticipantListener_on_liveliness_changed (inherited,

243API Reference

3 DCPS Classes and Operations 3.2 Domain Module

abstract)This operation is inherited and therefore not described here. See the classDDS_DataReaderListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_DomainParticipantListener_on_liveliness_changed (void *listener_data, DDS_DataReader reader, const DDS_LivelinessChangedStatus *status);

3.2.4.6 DDS_DomainParticipantListener_on_liveliness_lost (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_DataWriterListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_DomainParticipantListener_on_liveliness_lost (void *listener_data, DDS_DataWriter writer, const DDS_LivelinessLostStatus *status);

3.2.4.7 DDS_DomainParticipantListener_on_offered_deadline_missed (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_DataWriterListener for further explanation.Synopsis#include <dds_dcps.h>void DDS_DomainParticipantListener_on_offered_deadline_missed (void *listener_data, DDS_DataWriter writer, const DDS_OfferedDeadlineMissedStatus *status);

3.2.4.8 DDS_DomainParticipantListener_on_offered_incompatible_qos (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_DataWriterListener for further explanation.

Synopsis#include <dds_dcps.h>

244API Reference

3 DCPS Classes and Operations 3.2 Domain Module

void DDS_DomainParticipantListener_on_offered_incompatible_qos (void *listener_data, DDS_DataWriter writer, const DDS_OfferedIncompatibleQosStatus *status);

3.2.4.9 DDS_DomainParticipantListener_on_publication_matched (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_DataWriterListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_DomainParticipantListener_on_publication_matched (void *listener_data, DDS_DataWriter writer, const DDS_PublicationMatchedStatus *status);

3.2.4.10 DDS_DomainParticipantListener_on_requested_deadline_missed (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_DataReaderListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_DomainParticipantListener_on_requested_deadline_missed (void *listener_data, DDS_DataReader reader, const DDS_RequestedDeadlineMissedStatus *status);

3.2.4.11 DDS_DomainParticipantListener_on_requested_incompatible_qos (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_DataReaderListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_DomainParticipantListener_on_requested_incompatible_qos (void *listener_data, DDS_DataReader reader, const DDS_RequestedIncompatibleQosStatus *status);

245API Reference

3 DCPS Classes and Operations 3.2 Domain Module

3.2.4.12 DDS_DomainParticipantListener_on_sample_lost (inherited, abstract)This operation is inherited and therefore not described here. See the classDDS_DataReaderListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_DomainParticipantListener_on_sample_lost (void *listener_data, DDS_DataReader reader, const DDS_SampleLostStatus *status);

3.2.4.13 DDS_DomainParticipantListener_on_sample_rejected (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_DataReaderListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_DomainParticipantListener_on_sample_rejected (void *listener_data, DDS_DataReader reader, const DDS_SampleRejectedStatus *status);

3.2.4.14 DDS_DomainParticipantListener_on_subscription_matched (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_DataReaderListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_DomainParticipantListener_on_subscription_matched (void *listener_data, DDS_DataReader reader, const DDS_SubscriptionMatchedStatus *status);

3.2.5 DDS_ExtDomainParticipantListener interfaceThe ExtDomainParticipantListener interface is a subtype of bothDomainParticipantListener and ExtTopicListener and thereby providesan additional OpenSplice-specific callback, on_all_disposed_data, usablefrom the DomainParticipant.

246API Reference

3 DCPS Classes and Operations 3.2 Domain Module

All operations for this interface must be implemented in the user-defined class, it isup to the application whether an operation is empty or contains some functionality.

The interface description of this class is as follows:/* * interface DDS_ExtDomainParticipantListener *//* * inherited from DDS_TopicListener *//* void * DDS_ExtDomainParticipantListener_on_inconsistent_topic * (void *listener_data, * DDS_Topic the_topic, * const DDS_InconsistentTopicStatus *status); *//* * inherited from DDS_ExtTopicListener *//* void * DDS_ExtDomainParticipantListener_on_all_data_disposed * (void *listener_data, * DDS_Topic the_topic); *//* * inherited from DDS_PublisherListener *//* void * DDS_ExtDomainParticipantListener_on_offered_deadline_missed * (void *listener_data, * DDS_DataWriter writer, * const DDS_OfferedDeadlineMissedStatus *status); */ /* void * DDS_ExtDomainParticipantListener_on_offered_incompatible_qos * (void *listener_data, * DDS_DataWriter writer, * const DDS_OfferedIncompatibleQosStatus *status); */ /* void * DDS_ExtDomainParticipantListener_on_liveliness_lost * (void *listener_data, * DDS_DataWriter writer, * const DDS_LivelinessLostStatus *status); */

247API Reference

3 DCPS Classes and Operations 3.2 Domain Module

/* void * DDS_ExtDomainParticipantListener_on_publication_matched * (void *listener_data, * DDS_DataWriter writer, * const DDS_PublicationMatchedStatus *status); *//* * inherited from DDS_SubscriberListener *//* void * DDS_ExtDomainParticipantListener_on_data_on_readers * (void *listener_data, * DDS_Subscriber subs); *//* void * DDS_ExtDomainParticipantListener_on_requested_deadline_missed * (void *listener_data, * DDS_DataReader reader, * const DDS_RequestedDeadlineMissedStatus *status); */ /* void * DDS_ExtDomainParticipantListener_on_requested_incompatible_qos * (void *listener_data, * DDS_DataReader reader, * const DDS_RequestedIncompatibleQosStatus *status); */ /* void * DDS_ExtDomainParticipantListener_on_sample_rejected * (void *listener_data, * DDS_DataReader reader, * const DDS_SampleRejectedStatus *status); */ /* void * DDS_ExtDomainParticipantListener_on_liveliness_changed * (void *listener_data, * DDS_DataReader reader, * const DDS_LivelinessChangedStatus *status); */ /* void * DDS_ExtDomainParticipantListener_on_data_available * (void *listener_data, * DDS_DataReader reader); */ /* void * DDS_ExtDomainParticipantListener_on_subscription_matched

248API Reference

3 DCPS Classes and Operations 3.2 Domain Module

* (void *listener_data, * DDS_DataReader reader, * const DDS_SubscriptionMatchedStatus *status); */ /* void * DDS_ExtDomainParticipantListener_on_sample_lost * (void *listener_data, * DDS_DataReader reader, * const DDS_SampleLostStatus *status); *//* * implemented API operations */

struct DDS_ExtDomainParticipantListener * DDS_ExtDomainParticipantListener__alloc (void);

The following paragraphs list all ExtDomainParticipantListener operations.Since these operations are all inherited, they are listed but not fully describedbecause they are not implemented in this class. The full descriptions of theseoperations are given in the classes from which they are inherited.

3.2.5.1 DDS_ExtDomainParticipantListener__alloc

Synopsis#include <dds_dcps.h>struct DDS_ExtDomainParticipantListener * DDS_ExtDomainParticipantListener__alloc (void);

DescriptionThis operation creates a new DDS_ExtDomainParticipantListener.

Parameters<none>

Return Valuestruct DDS_ExtDomainParticipantListener * - Return value is the handle

to the newly-created DDS_ExtDomainParticipantListener. In case of anerror, a DDS_OBJECT_NIL pointer is returned.

Detailed DescriptionThis operation creates a new DDS_ExtDomainParticipantListener. TheDDS_ExtDomainParticipantListener must be created using this operation. Inother words, the application is not allowed to declare an object of type

249API Reference

3 DCPS Classes and Operations 3.2 Domain Module

DDS_ExtDomainParticipantListener. When the application wants to releasethe DDS_ExtDomainParticipantListener it must be released usingDDS_free.I n c a s e t h e r e a r e i n s u ff i c i e n t r e s o u r c e s a v a i l a b l e t o a l l o c a t e t h eDDS_ExtDomainParticipantListener, a DDS_OBJECT_NIL pointer isreturned instead.

3.2.5.2 DDS_ExtDomainParticipantListener_on_data_available (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_DataReaderListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_ExtDomainParticipantListener_on_data_available (void *listener_data, DDS_DataReader reader);

3.2.5.3 DDS_ExtDomainParticipantListener_on_data_on_readers (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_SubscriberListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_ExtDomainParticipantListener_on_data_on_readers (void *listener_data, DDS_Subscriber subs);

3.2.5.4 DDS_ExtDomainParticipantListener_on_inconsistent_topic (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_TopicListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_ExtDomainParticipantListener_on_inconsistent_topic (void *listener_data, DDS_Topic the_topic, const DDS_InconsistentTopicStatus *status);

250API Reference

3 DCPS Classes and Operations 3.2 Domain Module

3.2.5.5 DDS_ExtDomainParticipantListener_on_liveliness_changed (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_DataReaderListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_ExtDomainParticipantListener_on_liveliness_changed (void *listener_data, DDS_DataReader reader, const DDS_LivelinessChangedStatus *status);

3.2.5.6 DDS_ExtDomainParticipantListener_on_liveliness_lost (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_DataWriterListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_ExtDomainParticipantListener_on_liveliness_lost (void *listener_data, DDS_DataWriter writer, const DDS_LivelinessLostStatus *status);

3.2.5.7 DDS_ExtDomainParticipantListener_on_offered_deadline_missed (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_DataWriterListener for further explanation.Synopsis#include <dds_dcps.h>void DDS_ExtDomainParticipantListener_on_offered_deadline_missed (void *listener_data, DDS_DataWriter writer, const DDS_OfferedDeadlineMissedStatus *status);

3.2.5.8 DDS_ExtDomainParticipantListener_on_offered_incompatible_qos (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_DataWriterListener for further explanation.

251API Reference

3 DCPS Classes and Operations 3.2 Domain Module

Synopsis#include <dds_dcps.h>void DDS_ExtDomainParticipantListener_on_offered_incompatible_qos (void *listener_data, DDS_DataWriter writer, const DDS_OfferedIncompatibleQosStatus *status);

3.2.5.9 DDS_ExtDomainParticipantListener_on_publication_matched (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_DataWriterListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_ExtDomainParticipantListener_on_publication_matched (void *listener_data, DDS_DataWriter writer, const DDS_PublicationMatchedStatus *status);

3.2.5.10 DDS_ExtDomainParticipantListener_on_requested_deadline_missed (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_DataReaderListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_ExtDomainParticipantListener_on_requested_deadline_missed (void *listener_data, DDS_DataReader reader, const DDS_RequestedDeadlineMissedStatus *status);

3.2.5.11 DDS_ExtDomainParticipantListener_on_requested_incompatible_qos (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_DataReaderListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_ExtDomainParticipantListener_on_requested_incompatible_qos (void *listener_data, DDS_DataReader reader,

252API Reference

3 DCPS Classes and Operations 3.2 Domain Module

const DDS_RequestedIncompatibleQosStatus *status);

3.2.5.12 DDS_ExtDomainParticipantListener_on_sample_lost (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_DataReaderListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_ExtDomainParticipantListener_on_sample_lost (void *listener_data, DDS_DataReader reader, const DDS_SampleLostStatus *status);

3.2.5.13 DDS_ExtDomainParticipantListener_on_sample_rejected (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_DataReaderListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_ExtDomainParticipantListener_on_sample_rejected (void *listener_data, DDS_DataReader reader, const DDS_SampleRejectedStatus *status);

3.2.5.14 DDS_ExtDomainParticipantListener_on_subscription_matched (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_DataReaderListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_ExtDomainParticipantListener_on_subscription_matched (void *listener_data, DDS_DataReader reader, const DDS_SubscriptionMatchedStatus *status);

3.2.5.15 DDS_ExtDomainParticipantListener_on_all_data_disposed (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_ExtTopicListener for further explanation.

253API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

Synopsis#include <dds_dcps.h>void DDS_ExtDomainParticipantListener_on_all_data_disposed (DDS_Topic the_topic);

3.3 Topic-Definition Module

Figure 16: DCPS Topic-Definition Module Class ModelThis module contains the following classes:• DDS_TopicDescription (abstract)• DDS_Topic

• DDS_ContentFilteredTopic

• DDS_MultiTopic

• DDS_TopicListener (interface)• Topic-Definition type specific classes.

DomainEntity(from Infrastructure Module)

DataReader(from Subscription Module)

TypeSupport

get_type_name()register_type()

<<Interface>>

TopicDescription

get_name()get_participant()get_type_name()

1

*

1

*

11

DomainParticipant(from Domain Module)

TopicListener

on_inconsistent_topic()

<<Interface>>QosPolicy(from Infrastructure Module)

DataWriter(from Publication Module)

MultiTopic

get_expression_parameters()get_subscription_expression()set_expression_parameters()

ContentFilteredTopic

get_expression_parameters()get_filter_expression()get_related_topic()set_expression_parameters()

Topic

get_inconsistent_topic_status()get_listener()get_qos()set_listener()set_qos()

0..10..1**

1* 1*

**

11

WaitSet(from Infrastructure Module)

StatusCondition(from Infrastructure Module)

*

1

*

1

** **

<<create>>

<<create>>

<<create>>

254API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

“Topic-Definition type specific classes” contains the generic class and the generateddata type specific classes. For each data type, a data type specific class<NameSpace>_<type>TypeSupport is generated (based on IDL) by calling thepre-processor.

Figure 17: Pre-processor Generation of the Typed Classes for Data Type “Foo”

For instance, for the user-defined data type Foo (this also applies to other types),defined in the module SPACE; “Topic-Definition type specific classes” contains thefollowing classes:• DDS_TypeSupport (abstract)• SPACE_FooTypeSupport.DDS_Topic objects conceptually fit between publications and subscriptions.Publications must be known in such a way that subscriptions can refer to themunambiguously. A DDS_Topic is meant to fulfil that purpose: it associates a name(unique in the Domain), a data type, and DDS_TopicQos related to the data itself.

3.3.1 Class DDS_TopicDescription (abstract)This c lass i s an abs t rac t c lass . I t i s the base c lass for DDS_Topic ,DDS_ContentFilteredTopic and DDS_MultiTopic.The DDS_TopicDescription attribute type_name defines an unique data typethat is made available to the Data Distribution Service via the DDS_TypeSupport.DDS_TopicDescription has also a name that allows it to be retrieved locally.The interface description of this class is as follows:

TypeSupport

get_type_name()register_type()

<<Interface>> DataWriter(from Publication Module)

DataReader(from Subscription Module)

FooDataReader

get_key_value()read()read_instance()read_next_instance()read_next_instance_w_condition()read_next_sample()read_w_condition()return_loan()take()take_instance()take_next_instance()take_next_instance_w_condition()take_next_sample()take_w_condition()

FooDataWriter

dispose()dispose_w_timestamp()get_key_value()register()register_w_timestamp()unregister()unregister_w_timestamp()write()write_w_timestamp()

Foo

FooTypeSupport

get_type_name()register_type()

255API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

/* * interface DDS_TopicDescription *//* * implemented API operations */

DDS_string DDS_TopicDescription_get_type_name (DDS_TopicDescription _this);

DDS_string DDS_TopicDescription_get_name (DDS_TopicDescription _this);

DDS_DomainParticipant DDS_TopicDescription_get_participant (DDS_TopicDescription _this);

The next paragraphs describe the usage of all DDS_TopicDescriptionoperations.

3.3.1.1 DDS_TopicDescription_get_name

Synopsis#include <dds_dcps.h>DDS_string DDS_TopicDescription_get_name (DDS_TopicDescription _this);

DescriptionThis operation returns the name used to create the DDS_TopicDescription.

Parametersin DDS_TopicDescription _this - the DDS_TopicDescription object on

which the operation is operated.

Return ValueDDS_string - the name of the DDS_TopicDescription.

Detailed DescriptionThis operation returns the name used to create the DDS_TopicDescription.

3.3.1.2 DDS_TopicDescription_get_participant

Synopsis#include <dds_dcps.h>

256API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

DDS_DomainParticipant DDS_TopicDescription_get_participant (DDS_TopicDescription _this);

DescriptionThis operation returns the DDS_DomainParticipant associated with theDDS_TopicDescription or the DDS_OBJECT_NIL pointer.

Parametersin DDS_TopicDescription _this - the DDS_TopicDescription object on

which the operation is operated.

Return ValueDDS_DomainParticipant - a pointer to the DDS_DomainParticipant

associated with the DDS_TopicDescription or the DDS_OBJECT_NILpointer.

Detailed DescriptionThis operation returns the DDS_DomainParticipant associated with theDDS_TopicDescription . N o t e t h a t t h e r e i s e x a c t l y o n eDDS_DomainParticipant associated with each DDS_TopicDescription.When the DDS_TopicDescription was already deleted (there is no associatedDDS_DomainParticipant any more), the DDS_OBJECT_NIL pointer is returned.

3.3.1.3 DDS_TopicDescription_get_type_name

Synopsis#include <dds_dcps.h>DDS_string DDS_TopicDescription_get_type_name (DDS_TopicDescription _this);

DescriptionThis operation returns the registered name of the data type associated with theDDS_TopicDescription.

Parametersin DDS_TopicDescription _this - the DDS_TopicDescription object on

which the operation is operated.

Return ValueDDS_string - r e t u r n v a l u e i s t h e n a m e o f t he d a t a t yp e o f t h e

DDS_TopicDescription.

257

API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

Detailed DescriptionThis operation returns the registered name of the data type associated with theDDS_TopicDescription.

3.3.2 Class DDS_TopicDDS_Topic is the most basic description of the data to be published and subscribed.A DDS_Topic is identified by its name, which must be unique in the wholeDomain. In addition (by virtue of extending DDS_TopicDescription) it fullyidentifies the type of data that can be communicated when publishing or subscribingto the DDS_Topic.DDS_Topic is the only DDS_TopicDescription that can be used for publicationsand therefore a specialized DDS_DataWriter is associated to the DDS_Topic.The interface description of this class is as follows:

/* * interface DDS_Topic *//* * inherited from class DDS_Entity *//* DDS_StatusCondition * DDS_Topic_get_statuscondition * (DDS_Topic _this); *//* DDS_StatusMask * DDS_Topic_get_status_changes * (DDS_Topic _this); *//* DDS_ReturnCode_t * DDS_Topic_enable * (DDS_Topic _this); *//* * inherited from class DDS_TopicDescription *//* DDS_string * DDS_Topic_get_type_name * (DDS_Topic _this); */

/* DDS_string * DDS_Topic_get_name * (DDS_Topic _this); */

/* DDS_DomainParticipant

258API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

* DDS_Topic_get_participant * (DDS_Topic _this); *//* * implemented API operations */

DDS_ReturnCode_t DDS_Topic_set_qos (DDS_Topic _this, const DDS_TopicQos *qos);DDS_ReturnCode_t DDS_Topic_get_qos (DDS_Topic _this, DDS_TopicQos *qos);DDS_ReturnCode_t DDS_Topic_set_listener (DDS_Topic _this, const struct DDS_TopicListener *a_listener,

const DDS_StatusMask mask);struct DDS_TopicListener DDS_Topic_get_listener (DDS_Topic _this);DDS_ReturnCode_t DDS_Topic_get_inconsistent_topic_status (DDS_Topic _this,

DDS_InconsistentTopicStatus *a_status);DDS_ReturnCode_t dispose_all_data ();

The next paragraphs describe the usage of all DDS_Topic operations. The inheritedoperations are listed but not fully described because they are not implemented in thisclass. The full description of these operations is given in the classes from which theyare inherited.

3.3.2.1 DDS_Topic_enable (inherited)This operation is inherited and therefore not described here. See the classDDS_Entity for further explanation.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Topic_enable (DDS_Topic _this);

NOTE: This operation is not yet implemented. It is scheduled for a future release.

259API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

3.3.2.2 DDS_Topic_get_inconsistent_topic_status

Synopsis#include <dds_dcps.h>

DDS_ReturnCode_t DDS_Topic_get_inconsistent_topic_status (DDS_Topic _this, DDS_InconsistentTopicStatus *a_status);

DescriptionThis operation obtains the DDS_InconsistentTopicStatus of the DDS_Topic.

Parametersin DDS_Topic _this - the DDS_Topic object on which the operation is

operated.inout DDS_InconsistentTopicStatus *a_status - the contents of the

DDS_InconsistentTopicStatus struct of the DDS_Topic will be copiedinto the location specified by a_status.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:DDS_RETCODE_OK , DDS_RETCODE_ERROR , DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation obtains the DDS_InconsistentTopicStatus of the DDS_Topic.The DDS_InconsistentTopicStatus can also be monitored using aDDS_TopicListener or by using the associated DDS_StatusCondition.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the current DDS_InconsistentTopicStatus of thisDDS_Topic has successfully been copied into the specified a_status parameter.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_Topic has already been deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

260API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

3.3.2.3 DDS_Topic_get_listener

Synopsis#include <dds_dcps.h>struct DDS_TopicListener DDS_Topic_get_listener (DDS_Topic _this);

DescriptionThis operation allows access to a DDS_TopicListener.

Parametersin DDS_Topic _this - the DDS_Topic object on which the operation is

operated.

Return Valuestruct DDS_TopicListener - to the DDS_TopicListener attached to the

DDS_Topic.

Detailed DescriptionThis operation allows access to a DDS_TopicListener attached to theDDS_Topic. When no DDS_TopicListener was attached to the DDS_Topic, theDDS_OBJECT_NIL pointer is returned.

3.3.2.4 DDS_Topic_get_name (inherited)This operation is inherited and therefore not described here. See the classDDS_TopicDescription for further explanation.

Synopsis#include <dds_dcps.h>DDS_string DDS_Topic_get_name (DDS_Topic _this);

3.3.2.5 DDS_Topic_get_participant (inherited)This operation is inherited and therefore not described here. See the classDDS_TopicDescription for further explanation.

Synopsis#include <dds_dcps.h>DDS_DomainParticipant DDS_Topic_get_participant (DDS_Topic _this);

261API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

3.3.2.6 DDS_Topic_get_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Topic_get_qos (DDS_Topic _this, DDS_TopicQos *qos);

DescriptionThis operation allows access to the existing set of QoS policies for a DDS_Topic.

Parametersin DDS_Topic _this - the DDS_Topic object on which the operation is

operated.inout DDS_TopicQos *qos - a pointer to the destination DDS_TopicQos struct

in which the QosPolicy settings will be copied.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:DDS_RETCODE_OK , DDS_RETCODE_ERROR , DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation allows access to the existing set of QoS policies of a DDS_Topic onwhich this operation is used. This DDS_TopicQos is stored at the location pointedto by the qos parameter.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the existing set of QoS policy values applied to thisDDS_Topic has successfully been copied into the specified DDS_TopicQosparameter.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_Topic has already been deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

262API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

3.3.2.7 DDS_Topic_get_status_changes (inherited)This operation is inherited and therefore not described here. See the classDDS_Entity for further explanation.

Synopsis#include <dds_dcps.h>DDS_StatusMask DDS_Topic_get_status_changes (DDS_Topic _this);

3.3.2.8 DDS_Topic_get_statuscondition (inherited)This operation is inherited and therefore not described here. See the classDDS_Entity for further explanation.

Synopsis#include <dds_dcps.h>DDS_StatusCondition DDS_Topic_get_statuscondition (DDS_Topic _this);

3.3.2.9 DDS_Topic_get_type_name (inherited)This operation is inherited and therefore not described here. See the classDDS_TopicDescription for further explanation.

Synopsis#include <dds_dcps.h>DDS_string DDS_Topic_get_type_name (DDS_Topic _this);

3.3.2.10 DDS_Topic_set_listener

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Topic_set_listener (DDS_Topic _this, const struct DDS_TopicListener *a_listener, const DDS_StatusMask mask);

DescriptionThis operation attaches a DDS_TopicListener to the DDS_Topic.

263API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

Parametersin DDS_Topic _this - the DDS_Topic object on which the operation is

operated.in const struct DDS_TopicListener *a_listener - a pointer to the

DDS_TopicListener instance, which will be attached to the DDS_Topic.in const DDS_StatusMask mask - a bit-mask in which each bit enables the

invocation of the DDS_TopicListener for a certain status.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation attaches a DDS_TopicListener to the DDS_Topic. Only oneDDS_TopicListener c an b e a t t a c h e d t o e a c h DDS_Topic . I f aDDS_TopicListener was already attached, the operation will replace it with thenew one. When a_listener is the DDS_OBJECT_NIL pointer, it represents alistener that is treated as a NOOP1 for all statuses activated in the bitmask.

Communication StatusFor each communication status, the StatusChangedFlag flag is initially set toFALSE. It becomes TRUE whenever that plain communication status changes. Foreach plain communication status activated in the mask , the associatedDDS_TopicListener operation is invoked and the communication status is resetto FALSE, as the listener implicitly accesses the status which is passed as aparameter to that operation. The status is reset prior to calling the listener, so if theapplication calls the get_<status_name> from inside the listener it will see thestatus already reset. An exception to this rule is the DDS_OBJECT_NIL listener,which does not reset the communication statuses for which it is invoked.The following statuses are applicable to the DDS_TopicListener:• DDS_INCONSISTENT_TOPIC_STATUS.Status bits are declared as a constant and can be used by the application in an ORoperation to create a tailored mask. The special constant DDS_STATUS_MASK_NONEcan be used to indicate that the created entity should not respond to any of itsavailable statuses. The DDS will therefore attempt to propagate these statuses to its

1. Short for No-Operation, an instruction that peforms nothing at all.

264API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

factory. The special constant STATUS_MASK_ANY_V1_2 can be used to select allstatuses specified in the “Data Distribution Service for Real-time Systems Version1.2” specification.

Status PropagationIn case a communica t ion s ta tus i s not ac t iva ted in the mask o f theDDS_TopicListener, the DDS_DomainParticipantListener of thecontaining DDS_DomainParticipant is invoked (if attached and activated for thestatus that occurred). This allows the application to set a default behaviour in theDDS_DomainParticipantListener o f t h e c o n t a i n i n gDDS_DomainParticipant and a DDS_Topic specific behaviour when needed. Incase the DDS_DomainParticipantListener is also not attached or thecommunication status is not activated in its mask, the application is not notified ofthe change.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the DDS_TopicListener is attached.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_Topic has already been deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

3.3.2.11 DDS_Topic_set_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Topic_set_qos (DDS_Topic _this, const DDS_TopicQos *qos);

DescriptionThis operation replaces the existing set of QosPolicy settings for a DDS_Topic.

Parametersin DDS_Topic _this - the DDS_Topic object on which the operation is

operated.

265API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

in const DDS_TopicQos *qos - new set of QosPolicy settings for theDDS_Topic.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_UNSUPPORTED, DDS_RETCODE_ALREADY_DELETED , DDS_RETCODE_OUT_OF_RESOURCES , DDS_RETCODE_IMMUTABLE_POLICY o rDDS_RETCODE_INCONSISTENT_POLICY.

Detailed DescriptionThis replaces the existing set of QosPolicy settings for a DDS_Topic. Theparameter qos must contain the struct with the QosPolicy settings which ischecked for self-consistency and mutability. When the application tries to change aQosPolicy setting for an enabled DDS_Topic, which can only be set before theDDS_Topic i s e n a b l e d , t h e o p e r a t i o n w i l l f a i l a n d aDDS_RETCODE_IMMUTABLE_POLICY is returned. In other words, the applicationmust provide the currently set QosPolicy settings in case of the immutableQosPolicy settings. Only the mutable QosPolicy settings can be changed. Whenqos contains conflicting QosPolicy settings (not self-consistent), the operationwill fail and a DDS_RETCODE_INCONSISTENT_POLICY is returned.The set of QosPolicy settings specified by the qos parameter are applied on top ofthe existing QoS, replacing the values of any policies previously set (provided, theoperation returned DDS_RETCODE_OK).

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the new DDS_TopicQos is set.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter qos is not a validDDS_TopicQos. It contains a QosPolicy setting with an invalidDDS_Duration_t value, an enum value that is outside its legal boundaries or asequence that has inconsistent memory settings.

• DDS_RETCODE_UNSUPPORTED - one or more of the selected QosPolicy values arecurrently not supported by OpenSplice.

• DDS_RETCODE_ALREADY_DELETED - the DDS_Topic has already been deleted.

266API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_IMMUTABLE_POLICY - the parameter qos contains animmutable QosPolicy setting with a different value than set during enabling ofthe DDS_Topic.

• DDS_RETCODE_INCONSISTENT_POLICY - the parameter qos containsconflicting QosPolicy settings, e.g. a history depth that is higher than thespecified resource limits.

3.3.2.12 DDS_Topic_dispose_all_data

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t dispose_all_data ();

DescriptionThis operation allows the application to dispose of all of the instances for aparticular topic without the network overhead of using a separate dispose call foreach instance.

Parameters<none>

Return ValueDDS_ReturnCode_t - Poss ib le re turn codes of the opera t ion are :

DDS_RETCODE_OK , DDS_RETCODE_ERROR ,DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_ALREADY_DELETED,DDS_RETCODE_NOT_ENABLED.

DetailedDescriptionThis operation allows the application to dispose of all of the instances for aparticular topic without the network overhead of using a separate dispose call foreach instance. Its effect is equivalent to invoking a separate dispose operation foreach individual instance on the DataWriter that owns it. (See the description ofFooDataWriter.dispose in Section 3.4.2.33, SPACE_FooDataWriter_dispose,on page 349.)(The dispose_all_data is an asynchronous C&M operation that is not part of acoherent update; it operates on the DataReaders history cache and not on theincomplete transactions. The dispose_all_data is effectuated as soon as atransaction becomes complete and is inserted into the DataReaders history cache; atthat point messages will be inserted according to the destination_order qos

267API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

p o l i c y. F o r BY_SOURCE_TIMESTAMP a l l mes sa ges o lde r t han t hedispose_all_data will be disposed and all newer will be alive; forBY_RECEPTION_TIMESTAMP all messages will be alive if the transaction iscompleted after receiving the dispose_all_data command.)This operation only sets the instance state of the instances concerned toNOT_ALIVE_DISPOSED. It does not unregister the instances, and so does notautomatically clean up the memory that is claimed by the instances in both theDataReaders and DataWriters.

BlockingThe blocking (or nonblocking) behaviour of this call is undefined.

ConcurrencyIf there are subsequent calls to this function before the action has been completed(completion of the disposes on all nodes, not simply return from the function), thenthe behaviour is undefined.

Other notesThe effect of this call on disposed_generation_count, generation_rankand absolute_generation_rank is undefined.

Return Code• DDS_RETCODE_OK - a request to dispose the topic has been sucessfully queued.• DDS_RETCODE_ERROR - and internal error has occured.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_ALREADY_DELETED - the topic has already been deleted.• DDS_RETCODE_NOT_ENABLED - the topic is not enabled.

3.3.3 Class DDS_ContentFilteredTopicDDS_ContentFilteredTopic is a specialization of DDS_TopicDescriptionthat allows for content based subscriptions.DDS_ContentFilteredTopic describes a more sophisticated subscription thatindicates the DDS_Subscriber does not necessarily want to see all values of eachinstance published under the DDS_Topic. Rather, it only wants to see the valueswhose contents satisfy certain criteria. Therefore this class must be used to requestcontent-based subscriptions.The selection of the content is done using the SQL based filter with parameters toadapt the filter clause.

268API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

Appendix H, DCPS Queries and Filters describes the syntax of the SQL based filterand the parameters.The interface description of this class is as follows:

/* * interface DDS_ContentFilteredTopic *//* * inherited from class DDS_TopicDescription *//* DDS_string * DDS_ContentFilteredTopic_get_type_name * (DDS_ContentFilteredTopic _this);

*//* DDS_string * DDS_ContentFilteredTopic_get_name * (DDS_ContentFilteredTopic _this); */

/* DDS_DomainParticipant * DDS_ContentFilteredTopic_get_participant * (DDS_ContentFilteredTopic _this); *//* * implemented API operations */

DDS_string DDS_ContentFilteredTopic_get_filter_expression (DDS_ContentFilteredTopic _this);

DDS_ReturnCode_t DDS_ContentFilteredTopic_get_expression_parameters (DDS_ContentFilteredTopic _this, DDS_StringSeq *expression_parameters);

DDS_ReturnCode_t DDS_ContentFilteredTopic_set_expression_parameters (DDS_ContentFilteredTopic _this, const DDS_StringSeq *expression_parameters);

DDS_Topic DDS_ContentFilteredTopic_get_related_topic (DDS_ContentFilteredTopic _this);

/*

The next paragraphs describe the usage of all DDS_ContentFilteredTopicoperations.

269API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

3.3.3.1 DDS_ContentFilteredTopic_get_expression_parameters

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_ContentFilteredTopic_get_expression_parameters (DDS_ContentFilteredTopic _this, DDS_StringSeq *expression_parameters);

DescriptionThis operation obtains the expression parameters associated with theDDS_ContentFilteredTopic.

Parametersin DDS_ContentFilteredTopic _this - t h e

DDS_ContentFilteredTopic object on which the operation is operated.inout DDS_StringSeq *expression_parameters - a handle to a sequence of

strings that will be used to store the parameters used in the SQL expression.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation obtains the expression parameters associated with theDDS_ContentFilteredTopic. That is, the parameters specified on the lastsuccessful call to DDS_ContentFilteredTopic_set_expression_parameters, or if DDS_ContentFilteredTopic_set_expression_parameters was never ca l l ed , the paramete rs spec i f i ed when theDDS_ContentFilteredTopic was created.The resulting handle contains a sequence of strings with the parameters used in theSQL expression (i.e., the %n tokens in the expression). The number of parameters inthe result sequence will exactly match the number of %n tokens in the filterexpression associated with the DDS_ContentFilteredTopic.

Return CodeWhen the operation returns:

270API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

• DDS_RETCODE_OK - the existing set of expression parameters applied to thisDDS_ContentFilteredTopic has successfully been copied into the specifiedexpression_parameters parameter.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_ContentFilteredTopic has

already been deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

3.3.3.2 DDS_ContentFilteredTopic_get_filter_expression

Synopsis#include <dds_dcps.h>DDS_string DDS_ContentFilteredTopic_get_filter_expression (DDS_ContentFilteredTopic _this);

DescriptionThis operation returns the filter_expression associated with theDDS_ContentFilteredTopic.

Parametersin DDS_ContentFilteredTopic _this - the DDS_ContentFilteredTopic

object on which the operation is operated.

Return ValueDDS_string - result is a handle to a string which holds the SQL filter expression.

Detailed DescriptionThis operation returns the filter_expression associated with theDDS_ContentFilteredTopic. That is, the expression specified when theDDS_ContentFilteredTopic was created.The filter expression result is a string that specifies the criteria to select the datasamples of interest. It is similar to the WHERE clause of an SQL expression.

3.3.3.3 DDS_ContentFilteredTopic_get_name (inherited)This operation is inherited and therefore not described here. See the classDDS_TopicDescription for further explanation.

271API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

Synopsis#include <dds_dcps.h>DDS_string DDS_ContentFilteredTopic_get_name (DDS_ContentFilteredTopic _this);

3.3.3.4 DDS_ContentFilteredTopic_get_participant (inherited)This operation is inherited and therefore not described here. See the classDDS_TopicDescription for further explanation.

Synopsis#include <dds_dcps.h>DDS_DomainParticipant DDS_ContentFilteredTopic_get_participant (DDS_ContentFilteredTopic _this);

3.3.3.5 DDS_ContentFilteredTopic_get_related_topic

Synopsis#include <dds_dcps.h>DDS_Topic DDS_ContentFilteredTopic_get_related_topic (DDS_ContentFilteredTopic _this);

DescriptionT h i s o p e r a t i o n r e t u r n s t h e DDS_Topic a s soc i a t e d w i t h t h eDDS_ContentFilteredTopic.

Parametersin DDS_ContentFilteredTopic _this - the DDS_ContentFilteredTopic

object on which the operation is operated.

Return ValueDDS_Topic - result is a handle to the base topic on which the filtering will be

applied.

Detailed DescriptionT h i s o p e r a t i o n r e t u r n s t h e DDS_Topic a s soc i a t e d w i t h t h eDDS_ContentFilteredTopic. That is, the DDS_Topic specified when theDDS_ContentFilteredTopic was created. This DDS_Topic is the base topic onwhich the filtering will be applied.

272API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

3.3.3.6 DDS_ContentFilteredTopic_get_type_name (inherited)This operation is inherited and therefore not described here. See the classDDS_TopicDescription for further explanation.

Synopsis#include <dds_dcps.h>DDS_string DDS_ContentFilteredTopic_get_type_name (DDS_ContentFilteredTopic _this);

3.3.3.7 DDS_ContentFilteredTopic_set_expression_parameters

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_ContentFilteredTopic_set_expression_parameters (DDS_ContentFilteredTopic _this, const DDS_StringSeq *expression_parameters);

NOTE: This operation is not yet implemented. It is scheduled for a future release.

3.3.4 Class DDS_MultiTopicDDS_MultiTopic is a specialization of DDS_TopicDescription that allowssubscriptions to combine, filter and/or rearrange data coming from severalDDS_Topics.DDS_MultiTopic allows a more sophisticated subscription that can select andcombine data received from multiple DDS_Topics into a single data type (specifiedby the inherited type_name). The data will then be filtered (selection) and possiblyre-arranged (aggregation and/or projection) according to an SQL expression withparameters to adapt the filter clause.The interface description of this class is as follows: /*

* interface DDS_MultiTopic *//* * inherited from class DDS_TopicDescription *//* DDS_string * DDS_MultiTopic_get_type_name * (DDS_MultiTopic _this);

*//* DDS_string * DDS_MultiTopic_get_name * (DDS_MultiTopic _this); */

273API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

/* DDS_DomainParticipant * DDS_MultiTopic_get_participant * (DDS_MultiTopic _this); *//* * implemented API operations */

DDS_string DDS_MultiTopic_get_subscription_expression (DDS_MultiTopic _this);

DDS_ReturnCode_t DDS_MultiTopic_get_expression_parameters (DDS_MultiTopic _this, DDS_StringSeq *expression_parameters);

DDS_ReturnCode_t DDS_MultiTopic_set_expression_parameters (DDS_MultiTopic _this, const DDS_StringSeq *expression_parameters);

The next paragraphs describe the usage of all DDS_MultiTopic operations. Theinherited operations are listed but not fully described because they are notimplemented in this class. The full description of these operations is given in theclasses from which they are inherited.NOTE: DDS_MultiTopic operations have not been yet been implemented.Multitopic functionality is scheduled for a future release.

3.3.4.1 DDS_MultiTopic_get_expression_parameters

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_MultiTopic_get_expression_parameters (DDS_MultiTopic _this, DDS_StringSeq *expression_parameters);

NOTE: This operation is not yet implemented. It is scheduled for a future release.

DescriptionThis operation returns the expression parameters associated with theDDS_MultiTopic.

Parametersin DDS_MultiTopic _this - the DDS_MultiTopic object on which the

operation is operated.

274API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

inout DDS_StringSeq *expression_parameters - a handle to a sequence ofstrings that will be used to store the parameters used in the SQL expression.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation obtains the expression parameters associated with theDDS_MultiTopic. That is, the parameters specified on the last successful call toDDS_MultiTopic_set_expression_parameters , o r i fDDS_MultiTopic_set_expression_parameters was never called, theparameters specified when the DDS_MultiTopic was created.The resulting handle contains a sequence of strings with the values of the parametersused in the SQL expression (i.e., the %n tokens in the expression). The number ofparameters in the result sequence will exactly match the number of %n tokens in thefilter expression associated with the DDS_MultiTopic.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the existing set of expression parameters applied to thisDDS_MultiTopic has successfully been copied into the specifiedexpression_parameters parameter.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_MultiTopic has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

3.3.4.2 DDS_MultiTopic_get_name (inherited)This operation is inherited and therefore not described here. See the classDDS_TopicDescription for further explanation.

Synopsis#include <dds_dcps.h>DDS_string

275API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

DDS_MultiTopic_get_name (DDS_MultiTopic _this);

NOTE: This operation is not yet implemented. It is scheduled for a future release.

3.3.4.3 DDS_MultiTopic_get_participant (inherited)This operation is inherited and therefore not described here. See the classDDS_TopicDescription for further explanation.

Synopsis#include <dds_dcps.h>DDS_DomainParticipant DDS_MultiTopic_get_participant (DDS_MultiTopic _this);

NOTE: This operation is not yet implemented. It is scheduled for a future release.

3.3.4.4 DDS_MultiTopic_get_subscription_expression

Synopsis#include <dds_dcps.h>DDS_string DDS_MultiTopic_get_subscription_expression (DDS_MultiTopic _this);

NOTE: This operation is not yet implemented. It is scheduled for a future release.

DescriptionThis operation returns the subscription expression associated with theDDS_MultiTopic.

Parametersin DDS_MultiTopic _this - is the DDS_MultiTopic object on which the

operation is operated.

Return ValueDDS_string - a handle to a string which holds the SQL subscription expression.

Detailed DescriptionThis operation returns the subscription expression associated with theDDS_MultiTopic. That is, the expression specified when the DDS_MultiTopicwas created.The subscription expression result is a string that specifies the criteria to select thedata samples of interest. In other words, it identifies the selection and rearrangementof data from the associated DDS_Topics. It is an SQL expression where the

276API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

SELECT clause provides the fields to be kept, the FROM part provides the names ofthe DDS_Topics that are searched for those fields, and the WHERE clause gives thecontent filter. The DDS_Topics combined may have different types but they arerestricted in that the type of the fields used for the NATURAL JOIN operation mustbe the same.

3.3.4.5 DDS_MultiTopic_get_type_name (inherited)This operation is inherited and therefore not described here. See the classDDS_TopicDescription for further explanation.

Synopsis#include <dds_dcps.h>DDS_string DDS_MultiTopic_get_type_name (DDS_MultiTopic _this);

NOTE: This operation is not yet implemented. It is scheduled for a future release.

3.3.4.6 DDS_MultiTopic_set_expression_parameters

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_MultiTopic_set_expression_parameters (DDS_MultiTopic _this, const DDS_StringSeq *expression_parameters);

NOTE: This operation is not yet implemented. It is scheduled for a future release.

DescriptionThis operation changes the expression parameters associated with theDDS_MultiTopic.

Parametersin DDS_MultiTopic _this - the DDS_MultiTopic object on which the

operation is operated.in const DDS_StringSeq *expression_parameters - the handle to a

sequence of strings with the parameters used in the SQL expression.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

277API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

Detailed DescriptionThis operation changes the expression parameters associated with theDDS_MultiTopic. The parameter expression_parameters is a handle to asequence of strings with the parameters used in the SQL expression. The number ofparameters in expression_parameters must exactly match the number of %ntokens in the subscription expression associated with the DDS_MultiTopic. This isthe subscription expression specified when the DDS_MultiTopic was created.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the new expression parameters are set.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the number of parameters inexpression_parameters does not match the number of “%n” tokens in theexpression for this DDS_MultiTopic or one of the parameters is an illegalparameter.

• DDS_RETCODE_ALREADY_DELETED - the DDS_MultiTopic has already beendeleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

3.3.5 DDS_TopicListener InterfaceSince a DDS_Topic is a DDS_Entity, it has the ability to have a Listenerassociated with it. In this case, the associated Listener should be of typeDDS_TopicListener. This interface must be implemented by the application. Auser-defined class must be provided by the application which must extend from theDDS_TopicListener class. All DDS_TopicListener operations must beimplemented in the user-defined class, it is up to the application whether anoperation is empty or contains some functionality.

NOTE: All operations for this interface must be implemented in the user-definedclass, it is up to the application whether an operation is empty or contains somefunctionality.

The DDS_TopicListener provides a generic mechanism (actually a callbackfunction) for the Data Distribution Service to notify the application of relevantasynchronous status change events, such as an inconsistent DDS_Topic. TheDDS_TopicListener is related to changes in communication status.

278API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

The interface description of this class is as follows:/* * interface DDS_TopicListener *//* * abstract external operations *//* void * DDS_TopicListener_on_inconsistent_topic * (void *listener_data, * DDS_Topic the_topic, * const DDS_InconsistentTopicStatus *status); *//* * implemented API operations */

struct DDS_TopicListener * DDS_TopicListener__alloc (void);

The next paragraph describes the usage of the DDS_TopicListener operation.This abstract operation is fully described since it must be implemented by theapplication.

3.3.5.1 DDS_TopicListener__alloc

Synopsis#include <dds_dcps.h>struct DDS_TopicListener * DDS_TopicListener__alloc (void);

DescriptionThis operation creates a new DDS_TopicListener.

Parameters<none>

Return ValueDDS_TopicListener - the handle to the newly-created DDS_TopicListener. In

case of an error, a DDS_OBJECT_NIL pointer is returned.

279API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

Detailed DescriptionThis operation creates a new DDS_TopicListener. The DDS_TopicListenermust be created using this operation. In other words, the application is not allowedto declare an object of type DDS_TopicListener. When the application wants torelease the DDS_TopicListener it must be released using DDS_free.I n c a s e t h e r e a r e i n s u ff i c i e n t r e s o u r c e s a v a i l a b l e t o a l l o c a t e t h eDDS_TopicListener, a DDS_OBJECT_NIL pointer is returned instead.

3.3.5.2 DDS_TopicListener_on_inconsistent_topic (abstract)

Synopsis#include <dds_dcps.h>void DDS_TopicListener_on_inconsistent_topic (void *listener_data, DDS_Topic the_topic, const DDS_InconsistentTopicStatus *status);

DescriptionThis operation must be implemented by the application and is called by the DataDistribution Service when the DDS_InconsistentTopicStatus changes.

Parametersinout void *listener_data - a pointer to a user-defined object whichmay be used for identification of the Listener.in DDS_Topic the_topic - a pointer to the DDS_Topic on which theconflict occurred (this is an input to the application).in const DDS_InconsistentTopicStatus *status - theDDS_InconsistentTopicStatus struct (this is an input to the application).

Return Value<none>

Detailed DescriptionThis operation is the external operation (interface, which must be implemented bythe application) that is called by the Data Distribution Service when theDDS_InconsistentTopicStatus changes. The implementation may be leftempty when this functionality is not needed. This operation will only be called whenthe re levant DDS_TopicListener i s ins ta l led and enabled for the

280API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

DDS_InconsistentTopicStatus. The DDS_InconsistentTopicStatus willchange when another DDS_Topic exists with the same topic_name but differentcharacteristics.The Data Distribution Service will call the DDS_TopicListener operation with aparameter the_topic, which will contain a pointer to the DDS_Topic on whichthe conflict occurred and a parameter status , which will contain theDDS_InconsistentTopicStatus struct.

3.3.6 DDS_ExtTopicListener interfaceThe DDS_ExtTopicListener interface is a subtype of DDS_TopicListener andprovides an OpenSplice-specific callback on_all_disposed_data.

All operations for this interface must be implemented in the user-defined class, it isup to the application whether an operation is empty or contains some functionality.

The interface description of this class is as follows:/* * interface DDS_ExtTopicListener *//* * inherited from DDS_TopicListener *//* void * DDS_ExtTopicListener_on_inconsistent_topic * (void *listener_data, * DDS_Topic the_topic, * const DDS_InconsistentTopicStatus); *//* * abstract external operations *//* void * DDS_ExtTopicListener_on_all_data_disposed * (void *listener_data, * DDS_Topic the_topic); *//* * implemented API operations */struct DDS_ExtTopicListener *DDS_ExtTopicListener__alloc(void);

281API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

3.3.6.1 DDS_ExtTopicListener_on_all_data_disposed (abstract)

Synopsis#include <dds_dcps.h> void DDS_ExtTopicListener_on_all_data_disposed(void *listener_data, DDS_Topic the_topic);

DescriptionThis operation must be implemented by the application and is called by the DataDistribution Service when the node has completed disposal of data as a result of acall to DDS_Topic_dispose_all_data().

Parametersinout void *listener_data - a pointer to a user-defined object which may be

used for identification of the Listener.in DDS_Topic the_topic - contains a pointer to the Topic which has been

disposed.

Return Value<none>

Detailed DescriptionThis operation is the external operation (interface, which must be implemented bythe application) that is called by the Data Distribution Service when the node hasc o m p l e t e d d i s po s a l o f d a t a a s a r e s u l t o f a c a l l t oDDS_Topic_dispose_all_data().The implementation may be left empty when this functionality is not needed. Thisoperation will only be called when the relevant ExtTopicListener is installed.

ConcurrencyThe threading behaviour of calls to this method are undefined, so:• Subsequent disposal via DDS_Topic_dispose_all_data(), and the

associated callbacks may be blocked until this method returns.• This method may be called concurrently by OpenSplice if otherDDS_Topic_dispose_all_data() operations complete before this methodreturns.

282API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

3.3.7 Topic-Definition Type Specific ClassesThis paragraph describes the generic DDS_TypeSupport class and the derivedapplication type specific <NameSpace>_<type>TypeSupport classes whichtogether implement the application DDS_Topic interface. For each application type,u se d a s DDS_Topic d a t a t ype , t he p r e -p roce s s o r gene ra t e s a<NameSpace>_<type>DataReader class from an IDL type description. TheSPACE_FooTypeSupport class that would be generated by the pre-processor for af i c t i o na l t yp e Foo ( d e f i n e d i n t h e m o d u l e SPACE ) d e s c r i b e s t h e<NameSpace>_<type>TypeSupport classes.

3.3.7.1 Class DDS_TypeSupport (abstract)The DDS_Topic, DDS_MultiTopic or DDS_ContentFilteredTopic is boundto a data type described by the type name argument. Prior to creating a DDS_Topic,DDS_MultiTopic or DDS_ContentFilteredTopic, the data type must havebeen registered with the Data Distribution Service. This is done using the data typespecific DDS_TypeSupport_register_type operation on a derived class of theDDS_TypeSupport interface. A derived class is generated for each data type usedby the application, by calling the pre-processor.The interface description of this class is as follows:

/* * interface DDS_TypeSupport *//* * abstract operations *//* DDS_TypeSupport * DDS_TypeSupport__alloc * (void); *//* DDS_ReturnCode_t * DDS_TypeSupport_register_type * (DDS_TypeSupport _this, * Domainparticipant domain, * DDS_string type_name); * * DDS_string * DDS_TypeSupport_get_type_name * (DDS_TypeSupport _this); *//* * implemented API operations * <no operations> */

283API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

The next paragraph list the DDS_TypeSupport operation. This abstract operation islisted but not fully described since it is not implemented in this class. The fulldescription of this operation is given in the SPACE_FooTypeSupport class (for thedata type example Foo), which contains the data type specific implementation ofthis operation.

3.3.7.2 DDS_TypeSupport__alloc (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>TypeSupport class. Therefore, to use this operation,the data type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooTypeSupport class.

Synopsis#include <dds_dcps.h>DDS_TypeSupport DDS_TypeSupport__alloc (void);

3.3.7.3 DDS_TypeSupport_get_type_name (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>TypeSupport class. For further explanation see thedescription for the fictional data type Foo (defined in the module SPACE) derivedSPACE_FooTypeSupport class.

Synopsis#include <dds_dcps.h>DDS_string DDS_TypeSupport_get_type_name (DDS_TypeSupport _this);

3.3.7.4 DDS_TypeSupport_register_type (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>TypeSupport class. For further explanation see thedescription for the fictional data type Foo (defined in the module SPACE) derivedSPACE_FooTypeSupport class.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_TypeSupport_register_type (DDS_TypeSupport _this, Domainparticipant domain, DDS_string type_name);

284API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

3.3.7.5 Class SPACE_FooTypeSupportThe pre-processor generates from IDL type descriptions the application<NameSpace>_<type>TypeSupport classes. For each application data type thati s u s e d a s DDS_Topic d a t a t ype , a t yp ed c l a s s<NameSpace>_<type>TypeSupport is derived from the DDS_TypeSupportclass. In this paragraph, the class SPACE_FooTypeSupport describes theoperations of these derived <NameSpace>_<type>TypeSupport classes as anexample for the fictional application type Foo (defined in the module SPACE).For instance, for an application, the definitions are located in the Space.idl file.The pre-processor will generate a Space.h include file.The DDS_Topic, DDS_MultiTopic or DDS_ContentFilteredTopic is boundto a data type described by the type type_name argument. Prior to creating aDDS_Topic, DDS_MultiTopic or DDS_ContentFilteredTopic, the data typemust have been registered with the Data Distribution Service. This is done using thedata type specific SPACE_FooTypeSupport_register_type operation on the<NameSpace>_<type>TypeSupport class for each data type. A derived class isgenerated for each data type used by the application, by calling the pre-processor.The interface description of this class is as follows:

/* * interface SPACE_FooTypeSupport *//* * implemented API operations */

SPACE_FooTypeSupport SPACE_FooTypeSupport__alloc (void);DDS_ReturnCode_t SPACE_FooTypeSupport_register_type (SPACE_FooTypeSupport _this, DDS_DomainParticipant domain, DDS_string type_name);DDS_string SPACE_FooTypeSupport_get_type_name (SPACE_FooTypeSupport _this);

The next paragraph describes the usage of the SPACE_FooTypeSupportoperations.

3.3.7.6 SPACE_FooTypeSupport__alloc

Synopsis#include <Space.h>SPACE_FooTypeSupport

285API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

SPACE_FooTypeSupport__alloc (void);

DescriptionThis operation creates a new SPACE_FooTypeSupport.

Parameters<none>

Return ValueSPACE_FooTypeSupport - t h e h a n d l e t o t h e n e w l y - c r e a t e d

SPACE_FooTypeSupport. In case of an error, a nil pointer is returned.

Detailed DescriptionT h i s o p e r a t i o n c r e a t e s a n e w SPACE_FooTypeSupport . T h eSPACE_FooTypeSupport must be created using this operation. In other words, theapplication is not allowed to declare an object of type SPACE_FooTypeSupport.When the application wants to release the SPACE_FooTypeSupport it must bereleased using DDS_free.I n c a s e t h e r e a r e i n s u ff i c i e n t r e s o u r c e s a v a i l a b l e t o a l l o c a t e t h eSPACE_FooTypeSupport, a nil pointer is returned instead.

3.3.7.7 SPACE_FooTypeSupport_get_type_name

Synopsis#include <Space.h>DDS_string SPACE_FooTypeSupport_get_type_name (SPACE_FooTypeSupport _this);

DescriptionThis operation returns the default name of the data type associated with theSPACE_FooTypeSupport.

Parametersin SPACE_FooTypeSupport _this - the SPACE_FooTypeSupport object on

which the operation is operated.

Return ValueDDS_string - the name of the data type of the SPACE_FooTypeSupport.

286API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

Detailed DescriptionThis operation returns the default name of the data type associated with theSPACE_FooTypeSupport. The default name is derived from the type name asspecified in the IDL definition. It is composed of the scope names and the typename, each separated by “::”, in order of lower scope level to deeper scope levelfollowed by the type name.

3.3.7.8 SPACE_FooTypeSupport_register_type

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooTypeSupport_register_type (SPACE_FooTypeSupport _this, DDS_DomainParticipant domain, DDS_string type_name);

DescriptionThis operation registers a new data type name to a DDS_DomainParticipant.

Parametersin SPACE_FooTypeSupport _this - the SPACE_FooTypeSupport object on

which the operation is operated.in DDS_DomainParticipant domain - a p o i n t e r t o a

DDS_DomainParticipant object to which the new data type is registered.in DDS_string type_name - a local alias of the new data type to be registered.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionThis operation registers a new data type name to a DDS_DomainParticipant.This operation informs the Data Distribution Service, in order to allow it to managethe new registered data type. This operation also informs the Data DistributionService about the key definition, which allows the Data Distribution Service todistinguish different instances of the same data type.

287API Reference

3 DCPS Classes and Operations 3.3 Topic-Definition Module

PreconditionA type_name c anno t be r eg i s t e r ed w i th tw o d i f f e re n t<NameSpace>_<type>TypeSupport classes (this means of a different data type)with the same DDS_DomainParticipant. When the operation is called on thesame DDS_DomainParticipant with the same type_name for a different<NameSpace>_<type>TypeSupport c l a s s , t he ope ra t ion re tu rnsDDS_RETCODE_PRECONDITION_NOT_MET. However, it is possible to register thesame <NameSpace>_<type>TypeSupport c l a s ses wi th the sameDDS_DomainParticipant and the same or different type_name multiple times.All registrations return DDS_RETCODE_OK, but any subsequent registrations withthe same type_name are ignored.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the SPACE_FooTypeSupport class is registered with the

new data type name to the DDS_DomainParticipant or theSPACE_FooTypeSupport class was already registered.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - one or both of the parameters is invalid, thedomain parameter is the DDS_OBJECT_NIL pointer, or the parametertype_name has zero length.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_PRECONDITION_NOT_MET - this type_name is alreadyregistered with this DDS_DomainParticipant for a different<NameSpace>_<type>TypeSupport class.

288API Reference

3 DCPS Classes and Operations 3.4 Publication Module

3.4 Publication Module

Figure 18: The DCPS Publication Module’s Class Model

This module contains the following classes:• DDS_Publisher• Publication type specific classes• DDS_PublisherListener (interface)• DDS_DataWriterListener (interface).The paragraph “Publication type specific classes” contains the generic class and thegenerated data type specific classes. For each data type, a data type specific class<NameSpace>_<type>DataWriter is generated (based on IDL) by calling thepre-processor.For instance, for the fictional data type Foo (this also applies to other types), definedin the module SPACE; “Publication type specific classes” contains the followingclasses:• DDS_DataWriter (abstract)

WaitSet(from Infrastructure Module)

PublisherListener

<<Interface>>

DomainParticipant(from Domain Module)

DataWriterListener

on_liveliness_lost()on_offered_deadline_missed()on_offered_incompatible_qos()on_publication_match()

<<Interface>>

StatusCondition(from Infrastructure Module)

*

*

*

*

Publisher

begin_coherent_changes()copy_from_topic_qos()create_datawriter()delete_contained_entities()delete_datawriter()end_coherent_changes()get_default_datawriter_qos()get_listener()get_participant()get_qos()lookup_datawriter()resume_publications()set_default_datawriter_qos()set_listener()set_qos()suspend_publications()

1

*

1

*

<<implicit>>

1

0..1

1

0..1 <<implicit>>

QosPolicy(from Infrastructure Module)

**qos

<<implicit>>

**

default_datawriter_qos

DataWriter

assert_liveliness()<<abstract>> dispose()<<abstract>> dispose_w_timestamp()<<abstract>> get_key_value()get_listener()get_liveliness_lost_status()get_matched_subscription_data()get_matched_subscriptions()get_offered_deadline_missed_status()get_offered_incompatible_qos_status()get_publication_match_status()get_publisher()get_qos()get_topic()<<abstract>> register()<<abstract>> register_w_timestamp()set_listener()set_qos()<<abstract>> unregister()<<abstract>> unregister_w_timestamp()<<abstract>> write()<<abstract>> write_w_timestamp()

0..1

*

0..1

*

<<implicit>>

1

0..1

1

0..1

<<implicit>>

**

<<implicit>>

1

*

1

*

Topic(from Topic-Definition Module)

**

* 1* 1

<<create>>

<<create>>

289API Reference

3 DCPS Classes and Operations 3.4 Publication Module

• SPACE_FooDataWriter.A DDS_Publisher is an object responsible for data distribution. It may publishdata of different data types. A DDS_DataWriter acts as a typed accessor to aDDS_Publisher. The DDS_DataWriter is the object the application must use tocommunicate the existence and value of data-objects of a given data type to aDDS_Publisher. When data-object values have been communicated to theDDS_Publisher through the appropriate DDS_DataWriter, i t is theDDS_Publisher’s respons ib i l i ty to per form the d is t r ibu t ion . TheDDS_Publisher will do this according to its own DDS_PublisherQos, and theDDS_DataWriterQos attached to the corresponding DDS_DataWriter. Apublication is defined by the association of a DDS_DataWriter to aDDS_Publisher. This association expresses the intent of the application to publishthe data described by the DDS_DataWriter in the context provided by theDDS_Publisher.

3.4.1 Class DDS_PublisherThe DDS_Publisher acts on behalf of one or more DDS_DataWriter objects thatbelong to it. When it is informed of a change to the data associated with one of itsDDS_DataWriter objects, it decides when it is appropriate to actually process thesample -upda te message . In mak ing th i s dec i s ion , i t cons ide r s theDDS_PublisherQos and the DDS_DataWriterQos.The interface description of this class is as follows:

/* * interface DDS_Publisher *//* * inherited from class DDS_Entity *//* DDS_StatusCondition * DDS_Publisher_get_statuscondition * (DDS_Publisher _this); *//* DDS_StatusMask * DDS_Publisher_get_status_changes * (DDS_Publisher _this); *//* DDS_ReturnCode_t * DDS_Publisher_enable * (DDS_Publisher _this); *//* * implemented API operations */

DDS_DataWriter DDS_Publisher_create_datawriter

290API Reference

3 DCPS Classes and Operations 3.4 Publication Module

(DDS_Publisher _this, const DDS_Topic a_topic,

const DDS_DataWriterQos *qos, const struct DDS_DataWriterListener *a_listener, const DDS_StatusMask mask);

DDS_ReturnCode_t DDS_Publisher_delete_datawriter (DDS_Publisher _this, const DDS_DataWriter a_datawriter);

DDS_DataWriter DDS_Publisher_lookup_datawriter (DDS_Publisher _this, const DDS_char *topic_name);DDS_ReturnCode_t DDS_Publisher_delete_contained_entities (DDS_Publisher _this);

DDS_ReturnCode_t DDS_Publisher_set_qos (DDS_Publisher _this, const DDS_PublisherQos *qos);DDS_ReturnCode_t DDS_Publisher_get_qos (DDS_Publisher _this, DDS_PublisherQos *qos);DDS_ReturnCode_t DDS_Publisher_set_listener (DDS_Publisher _this, const struct DDS_PublisherListener *a_listener, const DDS_StatusMask mask);struct DDS_PublisherListener DDS_Publisher_get_listener (DDS_Publisher _this);DDS_ReturnCode_t DDS_Publisher_suspend_publications (DDS_Publisher _this);

DDS_ReturnCode_t DDS_Publisher_resume_publications (DDS_Publisher _this);

DDS_ReturnCode_t DDS_Publisher_begin_coherent_changes (DDS_Publisher _this);

DDS_ReturnCode_t DDS_Publisher_end_coherent_changes (DDS_Publisher _this);

291API Reference

3 DCPS Classes and Operations 3.4 Publication Module

DDS_ReturnCode_t DDS_Publisher_wait_for_acknowledgments (DDS_Publisher _this, const DDS_Duration_t *max_wait);

DDS_DomainParticipant DDS_Publisher_get_participant (DDS_Publisher _this);

DDS_ReturnCode_t DDS_Publisher_set_default_datawriter_qos (DDS_Publisher _this, const DDS_DataWriterQos *qos);

DDS_ReturnCode_t DDS_Publisher_get_default_datawriter_qos (DDS_Publisher _this, DDS_DataWriterQos *qos);

DDS_ReturnCode_t DDS_Publisher_copy_from_topic_qos (DDS_Publisher _this, DDS_DataWriterQos *a_datawriter_qos,

const DDS_TopicQos *a_topic_qos);

The following paragraphs describe the usage of all DDS_Publisher operations.The inherited operations are listed but not fully described because they are notimplemented in this class. The full description of these operations is given in theclasses from which they are inherited.

3.4.1.1 DDS_Publisher_begin_coherent_changes

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Publisher_begin_coherent_changes (DDS_Publisher _this);

DescriptionThis operation requests that the application will begin a ‘coherent set’ ofmodifications using DDS_DataWriter objects attached to this DDS_Publisher.The ‘coherent set’ will be completed by a matching call to DDS_Publisher_end_coherent_changes.

292API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Parametersin DDS_Publisher _this - the DDS_Publisher object on which the operation

is operated.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionThis operation requests that the application will begin a ‘coherent set’ ofmodifications using DDS_DataWriter objects attached to this DDS_Publisher.The ‘coherent set’ will be completed by a matching call to DDS_Publisher_end_coherent_changes.A ‘coherent set’ is a set of modifications that must be propagated in such a way thatthey are interpreted at the receivers’ side as a consistent set of modifications; that is,the receiver will only be able to access the data after all the modifications in the setare available at the receiver end.A precondition for making coherent changes is that the PresentationQos of theDDS_Publisher has its coherent_access attribute set to TRUE. If this is not thecase, the Publisher will not accept any coherent start requests and returnDDS_RETCODE_PRECONDITION_NOT_MET.A connectivity change may occur in the middle of a set of coherent changes; forexample, the set of partitions used by the DDS_Publisher or one of its connectedDDS_Subscribers may change, a late-joining DDS_DataReader may appear onthe network, or a communication failure may occur. In the event that such a changeprevents an entity from receiving the entire set of coherent changes, that entity mustbehave as if it had received none of the set.These calls can be nested. In that case, the coherent set terminates only with the lastcall to DDS_Publisher_end_coherent_changes.The support for ‘coherent changes’ enables a publishing application to change thevalue of several data-instances that could belong to the same or different topics andhave those changes be seen ‘atomically’ by the readers. This is useful in cases wherethe values are inter-related (for example, if there are two data-instances representingthe ‘altitude’ and ‘velocity vector’ of the same aircraft and both are changed, it maybe useful to communicate those values in a way the reader can see both together;otherwise, it may e.g., erroneously interpret that the aircraft is on a collision course).

293API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Return CodeWhen the operation returns:• DDS_RETCODE_OK - a new coherent change has successfully been started.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter passed to the operation is NULL,

or is not pointing to any valid object.• DDS_RETCODE_ALREADY_DELETED - the DDS_Publisher has already been

deleted.• DDS_RETCODE_PRECONDITION_NOT_MET - the DDS_Publisher is not able to

handle coherent changes because its PresentationQos has not setcoherent_access to TRUE.

3.4.1.2 DDS_Publisher_copy_from_topic_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Publisher_copy_from_topic_qos (DDS_Publisher _this, DDS_DataWriterQos *a_datawriter_qos, const DDS_TopicQos *a_topic_qos);

DescriptionThis operation will copy policies in a_topic_qos to the corresponding policies ina_datawriter_qos.

Parametersin DDS_Publisher _this - the DDS_Publisher object on which the operation

is operated.inout DDS_DataWriterQos *a_datawriter_qos - the destination

DDS_DataWriterQos struct to which the QosPolicy settings should becopied.

in const DDS_TopicQos *a_topic_qos - the source DDS_TopicQos struct,which should be copied.

294API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation will copy the QosPolicy settings in a_topic_qos to thecorresponding QosPolicy settings in a_datawriter_qos (replacing the valuesin a_datawriter_qos, if present). This will only apply to the commonQosPolicy settings in each <DDS_Entity>Qos.This is a “convenience” operation, useful in combination with the operationsDDS_Publisher_get_default_datawriter_qos and DDS_Topic_get_qos.The operation DDS_Publisher_copy_from_topic_qos can be used to mergethe DDS_DataWriter default QosPolicy settings with the corresponding ones onthe DDS_TopicQos. The resulting DDS_DataWriterQos can then be used tocreate a new DDS_DataWriter, or set its DDS_DataWriterQos.This operation does not check the resulting a_datawriter_qos for consistency.This is because the “merged” a_datawriter_qos may not be the final one, as theapplication can still modify some QosPolicy settings prior to applying theDDS_DataWriterQos to the DDS_DataWriter.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the QosPolicy settings have successfully been copied from

the DDS_TopicQos to the DDS_DataWriterQos.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_Publisher has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

3.4.1.3 DDS_Publisher_create_datawriter

Synopsis#include <dds_dcps.h>DDS_DataWriter DDS_Publisher_create_datawriter

295API Reference

3 DCPS Classes and Operations 3.4 Publication Module

(DDS_Publisher _this, const DDS_Topic a_topic, const DDS_DataWriterQos *qos, const struct DDS_DataWriterListener *a_listener, const DDS_StatusMask mask);

DescriptionT h i s o p e r a t i o n c r e a t e s a DDS_DataWriter w i t h t h e d e s i r e dDDS_DataWriterQos, for the desired DDS_Topic and attaches the optionallyspecified DDS_DataWriterListener to it.

Parametersin DDS_Publisher _this - the DDS_Publisher object on which the operation

is operated.in const DDS_Topic a_topic - a pointer to the topic for which the

DDS_DataWriter is created.in const DDS_DataWriterQos *qos - the DDS_DataWriterQos for the new

DDS_DataWriter. In case these settings are not self consistent, noDDS_DataWriter is created.

in const struct DDS_DataWriterListener *a_listener - a pointer tothe DDS_DataWriterListener instance which will be attached to the newDDS_DataWriter. It is permitted to use DDS_OBJECT_NIL as the value of thelistener: this behaves as a DDS_DataWriterListener whose operationsperform no action.

in const DDS_StatusMask mask - a bit-mask in which each bit enables theinvocation of the DDS_DataWriterListener for a certain status.

Return ValueDDS_DataWriter - Return value i s a poin ter to the newly-crea ted

DDS_DataWriter. In case of an error, the DDS_OBJECT_NIL pointer isreturned.

Detailed DescriptionT h i s o p e r a t i o n c r e a t e s a DDS_DataWriter w i t h t h e d e s i r e dDDS_DataWriterQos, for the desired DDS_Topic and attaches the optionallyspecified DDS_DataWriterListener to it. The returned DDS_DataWriter isattached (and belongs) to the DDS_Publisher on which this operation is beingcalled. To delete the DDS_DataWriter the operation DDS_Publisher_delete_datawriter or DDS_Publisher_delete_contained_entitiesmust be used. If no write rights are defined for the specific topic then the creation ofthe DataWriter will fail.

296API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Application Data TypeThe DDS_DataWriter returned by this operation is an object of a derived class,spec i f ic to the da ta type associa ted wi th the DDS_Topic . For eacha p p l i c a t i o n - d e f i n e d d a t a t y p e <type> t h e r e i s a c l a s s<NameSpace>_<type>DataWriter generated by calling the pre-processor. Thisdata type specific class extends DDS_DataWriter and contains the operations towrite data of data type <type>.

QosPolicyThe possible application pattern to construct the DDS_DataWriterQos for theDDS_DataWriter is to:• Retrieve the QosPolicy settings on the associated DDS_Topic by means of theget_qos operation on the DDS_Topic.

• Retrieve the default DDS_DataWriterQos by means of theDDS_Publisher_get_default_datawriter_qos operation on theDDS_Publisher

• Combine those two lists of QosPolicy settings and selectively modifyQosPolicy settings as desired

• Use the resulting DDS_DataWriterQos to construct the DDS_DataWriter.• In case the specified QosPolicy settings are not consistent, noDDS_DataWriter is created and the DDS_OBJECT_NIL pointer is returned.

Default QoSThe constant DDS_DATAWRITER_QOS_DEFAULT can be used as parameter qos tocreate a DDS_DataWriter with the default DDS_DataWriterQos as set in theDDS_Publisher. The effect of using DDS_DATAWRITER_QOS_DEFAULT is thesame as calling the operation DDS_Publisher_get_default_datawriter_qosand using the resulting DDS_DataWriterQos to create the DDS_DataWriter.The special DDS_DATAWRITER_QOS_USE_TOPIC_QOS can be used to create aDDS_DataWriter with a combination of the default DDS_DataWriterQos andthe DDS_TopicQos . T h e e f f e c t o f u s i n gDDS_DATAWRITER_QOS_USE_TOPIC_QOS is the same as calling the operationDDS_Publisher_get_default_datawriter_qos and retrieving theDDS_TopicQos (by means of the operation DDS_Topic_get_qos) and thencombin ing t he se two QosPolicy s e t t i n g s u s in g th e o p e r a t i o nDDS_Publisher_copy_from_topic_qos, whereby any common policy that isset on the DDS_TopicQos “overrides” the corresponding policy on the defaultDDS_DataWriterQos. The resulting DDS_DataWriterQos is then applied tocreate the DDS_DataWriter.

297API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Communication StatusFor each communication status, the StatusChangedFlag flag is initially set toFALSE. It becomes TRUE whenever that communication status changes. For eachco m m un ica t i on s t a t u s a c t i va t ed i n t he mask , t h e a s soc i a t e dDDS_DataWriterListener operation is invoked and the communication status isreset to FALSE, as the listener implicitly accesses the status which is passed as aparameter to that operation. The fact that the status is reset prior to calling thelistener means that if the application calls the get_<status_name>_status frominside the listener it will see the status already reset.The following statuses are applicable to the DDS_DataWriterListener:

DDS_OFFERED_DEADLINE_MISSED_STATUSDDS_OFFERED_INCOMPATIBLE_QOS_STATUSDDS_LIVELINESS_LOST_STATUSDDS_PUBLICATION_MATCHED_STATUS.

Be aware that the DDS_PUBLICATION_MATCHED_STATUS is not applicable whenthe infrastructure does not have the information available to determine connectivity.This is the case when OpenSplice is configured not to maintain discoveryinformation in the Networking Service. (See also the description of theNetworkService/Discovery[@enabled] attribute in section 4.4.1.6.1on page 244 of the Deployment Guide.) In this case the operation will returnDDS_OBJECT_NIL.Status bits are declared as a constant and can be used by the application in an ORoperation to create a tailored mask. The special constant DDS_STATUS_MASK_NONEcan be used to indicate that the created entity should not respond to any of itsavailable statuses. The DDS will therefore attempt to propagate these statuses to itsfactory. The special constant STATUS_MASK_ANY_V1_2 can be used to select allapplicable statuses specified in the “Data Distribution Service for Real-timeSystems Version 1.2” specification.

Status PropagationIn case a communica t ion s ta tus i s not ac t iva ted in the mask o f theDDS_DataWriterListener, the DDS_PublisherListener of the containingDDS_Publisher is invoked (if attached and activated for the status that occurred).T h i s a l l o w s t h e a p p l i c a t i o n to s e t a d e f a u l t b e h a v i o u r i n t h eDDS_PublisherListener of the containing DDS_Publisher and aDDS_DataWriter specific behaviour when needed. In case the communicationstatus is not activated in the mask of the DDS_PublisherListener as well, thec o m m u n i c a t i o n s t a t u s w i l l b e p r o p a g a t e d t o t h eDDS_DomainParticipantListener o f t h e c o n t a i n i n g

298API Reference

3 DCPS Classes and Operations 3.4 Publication Module

DDS_DomainParticipant. In case the DDS_DomainParticipantListener isalso not attached or the communication status is not activated in its mask, theapplication is not notified of the change.

3.4.1.4 DDS_Publisher_delete_contained_entities

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Publisher_delete_contained_entities (DDS_Publisher _this);

DescriptionThis operation deletes all the DDS_DataWriter objects that were created by meansof one of the DDS_Publisher_create_datawriter operations on theDDS_Publisher.

Parametersin DDS_Publisher _this - the DDS_Publisher object on which the operation

is operated.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_ALREADY_DELETED , DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionThis operation deletes all the DDS_DataWriter objects that were created by meansof one of the DDS_Publisher_create_datawriter operations on theDDS_Publisher. In other words, it deletes all contained DDS_DataWriterobjects.

NOTE: The operation will return DDS_PRECONDITION_NOT_MET if the any of thecontained entities is in a state where it cannot be deleted. In such cases, theoperation does not roll back any entity deletions performed prior to the detection ofthe problem.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the contained DDS_Entity objects are deleted and the

application may delete the DDS_Publisher.

299

API Reference

3 DCPS Classes and Operations 3.4 Publication Module

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_Publisher has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_PRECONDITION_NOT_MET - one or more of the contained entities

are in a state where they cannot be deleted.

3.4.1.5 DDS_Publisher_delete_datawriter

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Publisher_delete_datawriter (DDS_Publisher _this, const DDS_DataWriter a_datawriter);

DescriptionThis operation deletes a DDS_DataWriter that belongs to the DDS_Publisher.

Parametersin DDS_Publisher _this - the DDS_Publisher object on which the operation

-is operated.in const DDS_DataWriter a_datawriter - a p o i n t e r t o t h e

DDS_DataWriter, which is to be deleted.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_BAD_PARAMETER, DDS_RETCODE_ALREADY_DELETED , DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionThis operation deletes a DDS_DataWriter that belongs to the DDS_Publisher.When the operation is called on a different DDS_Publisher, as used when theDDS_DataWriter was created, the operation has no effect and returnsDDS_RETCODE_PRECONDITION_NOT_MET. The deletion of the DDS_DataWriter

300API Reference

3 DCPS Classes and Operations 3.4 Publication Module

will automatically unregister all instances. Depending on the settings ofDDS_WriterDataLifecycleQosPolicy, the deletion of the DDS_DataWritermay also dispose of all instances.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the DDS_DataWriter is deleted.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter a_datawriter is not a validDDS_DataWriter.

• DDS_RETCODE_ALREADY_DELETED - the DDS_Publisher has already beendeleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_PRECONDITION_NOT_MET - the operation is called on a differentDDS_Publisher, as used when the DDS_DataWriter was created.

3.4.1.6 DDS_Publisher_enable (inherited)This operation is inherited and therefore not described here. See the classDDS_Entity for further explanation.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Publisher_enable (DDS_Publisher _this);

3.4.1.7 DDS_Publisher_end_coherent_changes

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Publisher_end_coherent_changes (DDS_Publisher _this);

DescriptionThis operation terminates the ‘coherent set’ initiated by the matching call toDDS_Publisher_begin_coherent_changes.

301API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Parametersin DDS_Publisher _this - the DDS_Publisher object on which the operation

is operated.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionThis operation terminates the ‘coherent set’ initiated by the matching call toDDS_Publisher_begin_coherent_changes. If there is no matching call toDDS_Publisher_begin_coherent_changes, the operation will return the errorDDS_PRECONDITION_NOT_MET.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the coherent change has successfully been closed.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter passed to the operation is NULL,

or is not pointing to any valid object.• DDS_RETCODE_ALREADY_DELETED - the DDS_Publisher has already been

deleted.• DDS_RETCODE_PRECONDITION_NOT_MET - there is no matchingDDS_Publisher_begin_coherent_changes call that can be closed.

3.4.1.8 DDS_Publisher_get_default_datawriter_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Publisher_get_default_datawriter_qos (DDS_Publisher _this, DDS_DataWriterQos *qos);

DescriptionThis operation gets the default DDS_DataWriterQos of the DDS_Publisher.

302API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Parametersin DDS_Publisher _this - the DDS_Publisher object on which the operation

is operated.inout DDS_DataWriterQos *qos - a pointer to the DDS_DataWriterQos

struct (provided by the application) in which the default DDS_DataWriterQosfor the DDS_DataWriter is written.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation gets the default DDS_DataWriterQos of the DDS_Publisher (thatis the struct with the QosPolicy settings) which is used for newly-createdDDS_DataWriter objects, in case the constant DDS_DATAWRITER_QOS_DEFAULTis used. The default DDS_DataWriterQos is only used when the constant issupplied as parameter qos to specify the DDS_DataWriterQos in theDDS_Publisher_create_datawriter operation. The application must providethe DDS_DataWriterQos struct in which the QosPolicy settings can be storedand pass the qos pointer to the operation. The operation writes the defaultDDS_DataWriterQos to the struct pointed to by qos. Any settings in the struct areoverwritten.The values retrieved by this operation match the set of values specified on the lastsuccessful call to DDS_Publisher_set_default_datawriter_qos, or, if thecall was never made, the default values as specified for each QosPolicy setting asdefined in Table 5: on page 65.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the default DDS_DataWriter QosPolicy settings of thisDDS_Publisher have successfully been copied into the specifiedDDS_DataWriterQos parameter.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_Publisher has already been

deleted.

303API Reference

3 DCPS Classes and Operations 3.4 Publication Module

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

3.4.1.9 DDS_Publisher_get_listener

Synopsis#include <dds_dcps.h>struct DDS_PublisherListener DDS_Publisher_get_listener (DDS_Publisher _this);

DescriptionThis operation allows access to a DDS_PublisherListener.

Parametersin DDS_Publisher _this - the DDS_Publisher object on which the operation

is operated.

Return Valuestruct DDS_PublisherListener - a pointer to the DDS_PublisherListener

attached to the DDS_Publisher.

Detailed DescriptionThis operation allows access to a DDS_PublisherListener attached to theDDS_Publisher. When no DDS_PublisherListener was attached to theDDS_Publisher, the DDS_OBJECT_NIL pointer is returned.

3.4.1.10 DDS_Publisher_get_participant

Synopsis#include <dds_dcps.h>

DDS_DomainParticipant DDS_Publisher_get_participant (DDS_Publisher _this);

DescriptionThis operation returns the DDS_DomainParticipant associated with theDDS_Publisher or the DDS_OBJECT_NIL pointer.

Parametersin DDS_Publisher _this - the DDS_Publisher object on which the operation

is operated.

304API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Return ValueDDS_DomainParticipant - a pointer to the DDS_DomainParticipant

associated with the DDS_Publisher or the DDS_OBJECT_NIL pointer.

Detailed DescriptionThis operation returns the DDS_DomainParticipant associated with theDDS_Publisher. Note that there is exactly one DDS_DomainParticipantassociated with each DDS_Publisher. When the DDS_Publisher was alreadydeleted (there is no associated DDS_DomainParticipant any more), theDDS_OBJECT_NIL pointer is returned.

3.4.1.11 DDS_Publisher_get_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Publisher_get_qos (DDS_Publisher _this, DDS_PublisherQos *qos);

DescriptionThis operation allows access to the existing set of QoS policies for aDDS_Publisher.

Parametersin DDS_Publisher _this - the DDS_Publisher object on which the operation

is operated.inout DDS_PublisherQos *qos - a po in t e r t o t he de s t i na t i on

DDS_PublisherQos struct in which the QosPolicy settings will be copied.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation al lows access to the exist ing set of QoS policies of aDDS_Publisher on which this operation is used. This DDS_PublisherQos isstored at the location pointed to by the qos parameter.

305API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the existing set of QoS policy values applied to thisDDS_Publisher has successfully been copied into the specifiedDDS_PublisherQos parameter.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_Publisher has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

3.4.1.12 DDS_Publisher_get_status_changes (inherited)This operation is inherited and therefore not described here. See the classDDS_Entity for further explanation.

Synopsis#include <dds_dcps.h>DDS_StatusMask DDS_Publisher_get_status_changes (DDS_Publisher _this);

3.4.1.13 DDS_Publisher_get_statuscondition (inherited)This operation is inherited and therefore not described here. See the classDDS_Entity for further explanation.

Synopsis#include <dds_dcps.h>DDS_StatusCondition DDS_Publisher_get_statuscondition (DDS_Publisher _this);

3.4.1.14 DDS_Publisher_lookup_datawriter

Synopsis#include <dds_dcps.h>DDS_DataWriter DDS_Publisher_lookup_datawriter (DDS_Publisher _this, const DDS_char *topic_name);

306API Reference

3 DCPS Classes and Operations 3.4 Publication Module

DescriptionThis operation returns a previously created DDS_DataWriter belonging to theDDS_Publisher which is attached to a DDS_Topic with the matchingtopic_name.

Parametersin DDS_Publisher _this - the DDS_Publisher object on which the operation

is operated.in const DDS_char *topic_name - the name of the DDS_Topic, which is

attached to the DDS_DataWriter to look for.

Return ValueDDS_DataWriter - Return value is a pointer to the DDS_DataWriter found.

When no such DDS_DataWriter is found, the DDS_OBJECT_NIL pointer isreturned.

Detailed DescriptionThis operation returns a previously created DDS_DataWriter belonging to theDDS_Publisher which is attached to a DDS_Topic with the matchingtopic_name. When multiple DDS_DataWriter objects (which satisfy the samecondition) exist, this operation will return one of them. It is not specified which one.

3.4.1.15 DDS_Publisher_resume_publications

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Publisher_resume_publications (DDS_Publisher _this);

DescriptionThis operation resumes a previously suspended publication.

Parametersin DDS_Publisher _this - the DDS_Publisher object on which the operation

is operated.

307API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_ALREADY_DELETED , DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED or DDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionIf the DDS_Publisher is suspended, this operation will resume the publication ofall DDS_DataWriter objects contained by this DDS_Publisher. All data held inthe history buffer of the DDS_DataWriter's is actively published to the consumers.When the operation returns, all DDS_DataWriter's have resumed the publicationof suspended updates.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the DDS_Publisher object has been resumed.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_Publisher has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_NOT_ENABLED - the DDS_Publisher is not enabled.• DDS_RETCODE_PRECONDITION_NOT_MET - the DDS_Publisher is not

suspended.

3.4.1.16 DDS_Publisher_set_default_datawriter_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Publisher_set_default_datawriter_qos (DDS_Publisher _this, const DDS_DataWriterQos *qos);

DescriptionThis operation sets the default DDS_DataWriterQos of the DDS_Publisher.

308API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Parametersin DDS_Publisher _this - the DDS_Publisher object on which the operation

is operated.in const DDS_DataWriterQos *qos - the DDS_DataWriterQos struct, which

contains the new default DDS_DataWriterQos for the newly-createdDDS_DataWriters.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_UNSUPPORTED, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_INCONSISTENT_POLICY.

Detailed DescriptionThis operation sets the default DDS_DataWriterQos of the DDS_Publisher (thatis the struct with the QosPolicy settings) which is used for newly-createdDDS_DataWriter objects, in case the constant DDS_DATAWRITER_QOS_DEFAULTis used. The default DDS_DataWriterQos is only used when the constant issupplied as parameter qos to specify the DDS_DataWriterQos in theDDS_Publisher_create_datawriter operation. The DDS_Publisher_set_default_datawriter_qos operation checks if theDDS_DataWriterQos is self consistent. If it is not, the operation has no effect andreturns DDS_RETCODE_INCONSISTENT_POLICY.T h e v a l u e s s e t b y t h i s o p e r a t i o n a r e r e t u r n e d b yDDS_Publisher_get_default_datawriter_qos.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the new default DDS_DataWriterQos is set.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter qos is not a validDDS_DataWriterQos. It contains a QosPolicy setting with an invalidDDS_Duration_t value, an enum value that is outside its legal boundaries or asequence that has inconsistent memory settings.

• DDS_RETCODE_UNSUPPORTED - one or more of the selected QosPolicy values arecurrently not supported by OpenSplice.

309API Reference

3 DCPS Classes and Operations 3.4 Publication Module

• DDS_RETCODE_ALREADY_DELETED - the DDS_Publisher has already beendeleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_INCONSISTENT_POLICY - the parameter qos containsconflicting QosPolicy settings, e.g. a history depth that is higher than thespecified resource limits.

3.4.1.17 DDS_Publisher_set_listener

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Publisher_set_listener (DDS_Publisher _this, const struct DDS_PublisherListener *a_listener, const DDS_StatusMask mask);

DescriptionThis operation attaches a DDS_PublisherListener to the DDS_Publisher.

Parametersin DDS_Publisher _this - the DDS_Publisher object on which the operation

is operated.in const struct DDS_PublisherListener *a_listener - a pointer to the

DDS_PublisherListener instance, which will be attached to theDDS_Publisher.

in const DDS_StatusMask mask - a bit-mask in which each bit enables theinvocation of the DDS_PublisherListener for a certain status.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_UNSUPPORTED , DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation attaches a DDS_PublisherListener to the DDS_Publisher.Only one DDS_PublisherListener can be attached to each DDS_Publisher. Ifa DDS_PublisherListener was already attached, the operation will replace it

310API Reference

3 DCPS Classes and Operations 3.4 Publication Module

with the new one. When a_listener is the DDS_OBJECT_NIL pointer, itrepresents a listener that is treated as a NOOP1 for all statuses activated in thebitmask.

Communication StatusFor each communication status, the StatusChangedFlag flag is initially set toFALSE. It becomes TRUE whenever that communication status changes. For eachcommun ica t i on s t a t u s a c t i va t ed i n t he mask , t h e a s soc i a t e dDDS_PublisherListener operation is invoked and the communication status isreset to FALSE, as the listener implicitly accesses the status which is passed as aparameter to that operation. The status is reset prior to calling the listener, so if theapplication calls the get_<status_name>_status from inside the listener it willsee the status already reset. An exception to this rule is the DDS_OBJECT_NILlistener, which does not reset the communication statuses for which it is invoked.The following statuses are applicable to the DDS_PublisherListener:• DDS_OFFERED_DEADLINE_MISSED_STATUS (propagated)• DDS_OFFERED_INCOMPATIBLE_QOS_STATUS (propagated)• DDS_LIVELINESS_LOST_STATUS (propagated)• DDS_PUBLICATION_MATCHED_STATUS (propagated).Be aware that the DDS_PUBLICATION_MATCHED_STATUS is not applicable whenthe infrastructure does not have the information available to determine connectivity.This is the case when OpenSplice is configured not to maintain discoveryinformation in the Networking Service. (See also the description of theNetworkService/Discovery[@enabled] attribute in section 4.4.1.6.1on page 244 of the Deployment Guide.) In this case the operation will returnDDS_RETCODE_UNSUPPORTED.Status bits are declared as a constant and can be used by the application in an ORoperation to create a tailored mask. The special constant DDS_STATUS_MASK_NONEcan be used to indicate that the created entity should not respond to any of itsavailable statuses. The DDS will therefore attempt to propagate these statuses to itsfactory. The special constant STATUS_MASK_ANY_V1_2 can be used to select allapplicable statuses specified in the “Data Distribution Service for Real-timeSystems Version 1.2” specification.

Status PropagationThe Data Distribution Service will trigger the most specific and relevant Listener.In other words, in case a communication status is also activated on theDDS_DataWriterListener o f a conta ined DDS_DataWriter, the

1. Short for No-Operation, an instruction that peforms nothing at all.

311

API Reference

3 DCPS Classes and Operations 3.4 Publication Module

DDS_DataWriterListener on that contained DDS_DataWriter is invokedinstead of the DDS_PublisherListener. This means that a status change on acontained DDS_DataWriter only invokes the DDS_PublisherListener if thecontained DDS_DataWriter itself does not handle the trigger event generated bythe status change.In case a status is not activated in the mask of the DDS_PublisherListener, theDDS_DomainParticipantListener o f t h e c o n t a i n i n gDDS_DomainParticipant is invoked (if attached and activated for the status thatoccurred). This allows the application to set a default behaviour in theDDS_DomainParticipantListener o f t h e c o n t a i n i n gDDS_DomainParticipant and a DDS_Publisher specific behaviour whenneeded. In case the DDS_DomainParticipantListener is also not attached orthe communication status is not activated in its mask, the application is not notifiedof the change.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the DDS_PublisherListener is attached.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_UNSUPPORTED - a status was selected that cannot be supported

because the infrastructure does not maintain the required connectivityinformation.

• DDS_RETCODE_ALREADY_DELETED - the DDS_Publisher has already beendeleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

3.4.1.18 DDS_Publisher_set_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Publisher_set_qos (DDS_Publisher _this, const DDS_PublisherQos *qos);

DescriptionThis operation replaces the exist ing set of QosPolicy set t ings for aDDS_Publisher.

312API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Parametersin DDS_Publisher _this - the DDS_Publisher object on which the operation

is operated.in const DDS_PublisherQos *qos - contains the new set of QosPolicy

settings for the DDS_Publisher.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_UNSUPPORTED, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_IMMUTABLE_POLICY o rDDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionThis operation replaces the exist ing set of QosPolicy set t ings for aDDS_Publisher. The parameter qos contains the QosPolicy settings which ischecked for self-consistency and mutability. When the application tries to change aQosPolicy setting for an enabled DDS_Publisher, which can only be set beforethe DDS_Publisher i s enab l e d , t he ope r a t i o n w i l l f a i l a n d aDDS_RETCODE_IMMUTABLE_POLICY is returned. In other words, the applicationmust provide the currently set QosPolicy settings in case of the immutableQosPolicy settings. Only the mutable QosPolicy settings can be changed. Whenqos contains conflicting QosPolicy settings (not self-consistent), the operationwill fail and a DDS_RETCODE_INCONSISTENT_POLICY is returned.The set of QosPolicy settings specified by the qos parameter are applied on top ofthe existing QoS, replacing the values of any policies previously set (provided, theoperation returned DDS_RETCODE_OK). If one or more of the partitions in the QoSstructure have insufficient access rights configured then the set_qos function willfail with a DDS_RETCODE_PRECONDITION_NOT_MET error code.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the new DDS_PublisherQos is set.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter qos is not a validDDS_PublisherQos. It contains a QosPolicy setting with an enum value that isoutside its legal boundaries or a sequence that has inconsistent memory settings.

313API Reference

3 DCPS Classes and Operations 3.4 Publication Module

• DDS_RETCODE_UNSUPPORTED - one or more of the selected QosPolicy valuesare currently not supported by OpenSplice.

• DDS_RETCODE_ALREADY_DELETED - the DDS_Publisher has already beendeleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_IMMUTABLE_POLICY - the parameter qos contains an immutableQosPolicy setting with a different value than set during enabling of theDDS_Publisher.

• DDS_RETCODE_PRECONDITION_NOT_MET - returned when insufficient accessrights exist for the partition(s) listed in the QoS structure.

3.4.1.19 DDS_Publisher_suspend_publications

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Publisher_suspend_publications (DDS_Publisher _this);

DescriptionThis operation will suspend the dissemination of the publications by all containedDataWriter objects.

Parametersin DDS_Publisher _this - the DDS_Publisher object on which the operation

is operated.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_ALREADY_DELETED , DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_NOT_ENABLED.

Detailed DescriptionThis operation suspends the publication of all DDS_DataWriter objects containedby this DDS_Publisher. The data written, disposed or unregistered by aDDS_DataWriter is stored in the history buffer of the DDS_DataWriter andtherefore, depending on its QoS settings, the following operations may block (seethe operation descriptions for more information):• DDS_DataWriter_dispose

314API Reference

3 DCPS Classes and Operations 3.4 Publication Module

• DDS_DataWriter_dispose_w_timestamp

• DDS_DataWriter_write • DDS_DataWriter_write_w_timestamp • DDS_DataWriter_writedispose • DDS_DataWriter_writedispose_w_timestamp • DDS_DataWriter_unregister_instance • DDS_DataWriter_unregister_instance_w_timestamp Subsequent calls to the DDS_Publisher_suspend_publications operationha ve no e f f e c t . Whe n the DDS_Publisher i s de l e t e d be fo reDDS_Publisher_resume_publications is called, all suspended updates arediscarded.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the DDS_Publisher has been suspended.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_Publisher has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_NOT_ENABLED - the DDS_Publisher is not enabled.

3.4.1.20 DDS_Publisher_wait_for_acknowledgments

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Publisher_wait_for_acknowledgments (DDS_Publisher _this, const DDS_Duration_t *max_wait);

DescriptionThis operation blocks the calling thread until either all data written by all containedDataWriters is acknowledged by the local infrastructure, or until the durationspecified by max_wait parameter elapses, whichever happens first.

315API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Parametersin DDS_Publisher _this - the DDS_Publisher object on which the operation

is operated.in const DDS_Duration_t *max_wait - the maximum duration to block for

the DDS_Publisher_wait_for_acknowledgments, after which theap p l i ca t i on t h r ea d i s un b lo cke d . The sp ec i a l c ons t a n tDDS_DURATION_INFINITE can be used when the maximum waiting time doesnot need to be bounded.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_ALREADY_DELETED , DDS_RETCODE_OUT_OF_RESOURCES , DDS_RETCODE_NOT_ENABLED o rDDS_RETCODE_TIMEOUT.

Detailed DescriptionThis operation blocks the calling thread until either all data written by all containedDataWriters is acknowledged by the local infrastructure, or until the durationspecified by max_wait parameter elapses, whichever happens first.Data is acknowledged by the local infrastructure when it does not need to be storedin its DataWriter’s local history. When a locally-connected subscription (includingthe networking service) has no more resources to store incoming samples it will startto reject these samples, resulting in their source DataWriters to store themtemporarily in their own local history to be retransmitted at a later moment in time.In such scenarios, the DDS_Publisher_wait_for_acknowledgments operationwill block until all contained DataWriters have retransmitted their entire history,which is therefore effectively empty, or until the max_wait timeout expires,whichever happens f i r s t . In the f i r s t case the opera t ion wi l l re turnDDS_RETCODE_OK, in the latter it will return DDS_RETCODE_TIMEOUT.Be aware that in case the operation returns DDS_RETCODE_OK, the data has onlybeen acknowledged by the local infrastructure: it does not mean all remotesubscriptions have already received the data. However, delivering the data to remotenodes is then the sole responsibility of the networking service: even when thepublishing application would terminate, all data that has not yet been received maybe considered ‘on-route’ and will therefore eventually arrive (unless the networkingservice itself crashes). In contrast, if a DataWriter would still have data in its localhistory buffer when it terminates, this data is considered ‘lost’.

316API Reference

3 DCPS Classes and Operations 3.4 Publication Module

This operation is intended to be used only if one or more of the containedDa taWr i t e r s ha s i t s DDS_ReliabilityQosPolicyKind s e t t oDDS_RELIABLE_RELIABILITY_QOS. Otherwise the operation will returnimmediately with DDS_RETCODE_OK, since best-effort DataWriters will never storerejected samples in their local history: they will just drop them and continuebusiness as usual.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the data of all contained DataWriters has been acknowledged

by the local infrastructure.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_Publisher has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_NOT_ENABLED - the DDS_Publisher is not enabled.• DDS_RETCODE_TIMEOUT - not all data is acknowledged before max_wait

elapsed.

3.4.2 Publication Type Specific ClassesThis paragraph describes the generic DDS_DataWriter class and the derivedapplication type specific <NameSpace>_<type>DataWriter classes whichtogether implement the application publication interface. For each application type,u se d a s DDS_Topic d a t a t ype , t he p r e -p roce s s o r gene ra t e s a<NameSpace>_<type>DataWriter class from an IDL type description. TheSPACE_FooDataWriter class that would be generated by the pre-processor for af i c t i o na l t yp e Foo ( d e f i n e d i n t h e m o d u l e SPACE ) d e s c r i b e s t h e<NameSpace>_<type>DataWriter classes.

3.4.2.1 Class DDS_DataWriter (abstract)DDS_DataWriter allows the application to set the value of the sample to bepublished under a given DDS_Topic.A DDS_DataWriter is attached to exactly one DDS_Publisher which acts as afactory for it.

317API Reference

3 DCPS Classes and Operations 3.4 Publication Module

A DDS_DataWriter is bound to exactly one DDS_Topic and therefore to exactlyone data type. The DDS_Topic must exist prior to the DDS_DataWriter'screation.DDS_DataWriter is an abstract class. It must be specialized for each particularapplication data type. For a fictional application data type Foo (defined in themodule SPACE) the specialized class would be SPACE_FooDataWriter.The interface description of this class is as follows:

/* * interface DDS_DataWriter *//* * inherited from class DDS_Entity *//* DDS_StatusCondition * DDS_DataWriter_get_statuscondition * (DDS_DataWriter _this); *//* DDS_StatusMask * DDS_DataWriter_get_status_changes * (DDS_DataWriter _this); *//* DDS_ReturnCode_t * DDS_DataWriter_enable * (DDS_DataWriter _this); *//* * abstract operations * (implemented in the data type specific DDS_DataWriter) *//* DDS_InstanceHandle_t * DDS_DataWriter_register_instance * (DDS_DataWriter _this); * const <data> *instance_data); *//* DDS_InstanceHandle_t * DDS_DataWriter_register_instance_w_timestamp * (DDS_DataWriter _this); * const <data> *instance_data, * const DDS_Time_t *source_timestamp); *//* DDS_ReturnCode_t * DDS_DataWriter_unregister_instance * (DDS_DataWriter _this); * const <data> *instance_data, * const DDS_InstanceHandle_t handle); *//* DDS_ReturnCode_t

318API Reference

3 DCPS Classes and Operations 3.4 Publication Module

* DDS_DataWriter_unregister_instance_w_timestamp * (DDS_DataWriter _this); * const <data> *instance_data, * const DDS_InstanceHandle_t handle, * const DDS_Time_t *source_timestamp); *//* DDS_ReturnCode_t * DDS_DataWriter_write * (DDS_DataWriter _this); * const <data> *instance_data, * const DDS_InstanceHandle_t handle); *//* DDS_ReturnCode_t * DDS_DataWriter_write_w_timestamp * (DDS_DataWriter _this); * const <data> *instance_data, * const DDS_InstanceHandle_t handle, * const DDS_Time_t *source_timestamp); *//* DDS_ReturnCode_t * DDS_DataWriter_dispose * (DDS_DataWriter _this); * const <data> *instance_data, * const DDS_InstanceHandle_t instance_handle); *//* DDS_ReturnCode_t * DDS_DataWriter_dispose_w_timestamp * (DDS_DataWriter _this); * const <data> *instance_data, * const DDS_InstanceHandle_t instance_handle, * const DDS_Time_t *source_timestamp); *//* DDS_ReturnCode_t * DDS_DataWriter_writedispose * (DDS_DataWriter _this, * const <data> *instance_data, * const DDS_InstanceHandle_t instance_handle); *//* DDS_ReturnCode_t * DDS_DataWriter_writedispose_w_timestamp * (DDS_DataWriter _this, * const <data> *instance_data, * const DDS_InstanceHandle_t instance_handle, * const DDS_Time_t *source_timestamp);

*//* DDS_ReturnCode_t * DDS_DataWriter_get_key_value * (DDS_DataWriter _this); * <data> *key_holder,

319API Reference

3 DCPS Classes and Operations 3.4 Publication Module

* const DDS_InstanceHandle_t handle); *//* DDS_InstanceHandle_t * DDS_DataWriter_lookup_instance */ (DDS_DataWriter _this, * <data> *instance_data);/*/* * implemented API operations */

DDS_ReturnCode_t DDS_DataWriter_set_qos (DDS_DataWriter this, const DDS_DataWriterQos *qos);

DDS_ReturnCode_t DDS_DataWriter_get_qos (DDS_DataWriter this, DDS_DataWriterQos *qos);

DDS_ReturnCode_t DDS_DataWriter_set_listener (DDS_DataWriter this, const struct DDS_DataWriterListener *a_listener,

const DDS_StatusMask mask);

struct DDS_DataWriterListener struct DDS_DataWriter_get_listener (DDS_DataWriter this);

DDS_Topic DDS_DataWriter_get_topic (DDS_DataWriter this);

DDS_Publisher DDS_DataWriter_get_publisher (DDS_DataWriter this);

DDS_ReturnCode_t DDS_DataWriter_wait_for_acknowledgments (DDS_DataWriter _this, const DDS_Duration_t *max_wait);

DDS_ReturnCode_t DDS_DataWriter_get_liveliness_lost_status (DDS_DataWriter this, DDS_LivelinessLostStatus *status);

DDS_ReturnCode_t DDS_DataWriter_get_offered_deadline_missed_status

320API Reference

3 DCPS Classes and Operations 3.4 Publication Module

(DDS_DataWriter this, DDS_OfferedDeadlineMissedStatus *status);

DDS_ReturnCode_t DDS_DataWriter_get_offered_incompatible_qos_status (DDS_DataWriter this, DDS_OfferedIncompatibleQosStatus *status);

DDS_ReturnCode_t DDS_DataWriter_get_publication_matched_status (DDS_DataWriter this, DDS_PublicationMatchedStatus *status);

DDS_ReturnCode_t DDS_DataWriter_assert_liveliness (DDS_DataWriter this);

DDS_ReturnCode_t DDS_DataWriter_get_matched_subscriptions (DDS_DataWriter this, DDS_InstanceHandleSeq *subscription_handles);

DDS_ReturnCode_t DDS_DataWriter_get_matched_subscription_data (DDS_DataWriter this, DDS_SubscriptionBuiltinTopicData

*subscription_data, const DDS_InstanceHandle_t subscription_handle

);

The following paragraphs describe the usage of all DDS_DataWriter operations.The inherited operations are listed but not fully described because they are notimplemented in this class. The full description of these operations is given in theclasses from which they are inherited. The abstract operations are listed but not fullydescribed because they are not implemented in this specific class. The fulldescription of these operations is located in the subclasses, which contain the datatype specific implementation of these operations.

3.4.2.2 DDS_DataWriter_assert_liveliness

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataWriter_assert_liveliness (DDS_DataWriter _this);

DescriptionThis operation asserts the liveliness for the DDS_DataWriter.

321API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Parametersin DDS_DataWriter _this - is the DDS_DataWriter object on which the

operation is operated.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_ALREADY_DELETED , DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_NOT_ENABLED.

Detailed DescriptionThis operation will manually assert the liveliness for the DDS_DataWriter. Thisway, the Data Distribution Service is informed that the correspondingDDS_DataWriter is still alive. This operation is used in combination with theDDS_LivelinessQosPolicy set to DDS_MANUAL_BY_PARTICIPANT_LIVELINESS_QOS or DDS_MANUAL_BY_TOPIC_LIVELINESS_QOS. See Section3.1.3.10, DDS_LivelinessQosPolicy, on page 85, for more information onLivelinessQosPolicy.Writing data via the DDS_DataWriter_write operation of a DDS_DataWriterwill assert the liveliness on the DDS_DataWriter itself and its containingDDS_DomainParticipant . Therefore, DDS_DataWriter_assert_liveliness is only needed when data is not written regularly.The liveliness should be asserted by the application, depending on theDDS_LivelinessQosPolicy. Asserting the liveliness for this DDS_DataWritercan also be achieved by asserting the liveliness to the DDS_DomainParticipant.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the liveliness of this DDS_DataWriter has successfully

been asserted.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_DataWriter has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_NOT_ENABLED - the DDS_DataWriter is not enabled.

322API Reference

3 DCPS Classes and Operations 3.4 Publication Module

3.4.2.3 DDS_DataWriter_dispose (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataWriter class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataWriter class.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataWriter_dispose (DDS_DataWriter _this,

const <data> *instance_data, const DDS_InstanceHandle_t instance_handle);

3.4.2.4 DDS_DataWriter_dispose_w_timestamp (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataWriter class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataWriter class.

Synopsis#include <dds_dcps.h>

DDS_ReturnCode_t DDS_DataWriter_dispose_w_timestamp

(DDS_DataWriter _this, const <data> *instance_data, const DDS_InstanceHandle_t instance_handle, const DDS_Time_t *source_timestamp);

3.4.2.5 DDS_DataWriter_enable (inherited)This operation is inherited and therefore not described here. See the classDDS_Entity for further explanation.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataWriter_enable (DDS_DataWriter _this);

323API Reference

3 DCPS Classes and Operations 3.4 Publication Module

3.4.2.6 DDS_DataWriter_get_key_value (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataWriter class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataWriter class.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataWriter_get_key_value (DDS_DataWriter _this,

<data> *key_holder,const DDS_InstanceHandle_t handle);

3.4.2.7 DDS_DataWriter_get_listener

Synopsis#include <dds_dcps.h>struct DDS_DataWriterListener DDS_DataWriter_get_listener (DDS_DataWriter _this);

DescriptionThis operation allows access to a DDS_DataWriterListener.

Parametersin DDS_DataWriter _this - the DDS_DataWriter object on which the

operation is operated.

Return Valuestruct DDS_DataWriterListener - a p o i n t e r t o t h e

DDS_DataWriterListener attached to the DDS_DataWriter.

Detailed DescriptionThis operation allows access to a DDS_DataWriterListener attached to theDDS_DataWriter. When no DDS_DataWriterListener was attached to theDDS_DataWriter, the DDS_OBJECT_NIL pointer is returned.

3.4.2.8 DDS_DataWriter_get_liveliness_lost_status

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t

324API Reference

3 DCPS Classes and Operations 3.4 Publication Module

DDS_DataWriter_get_liveliness_lost_status (DDS_DataWriter _this, DDS_LivelinessLostStatus *status);

DescriptionThis operation obtains the DDS_LivelinessLostStatus struct of theDDS_DataWriter.

Parametersin DDS_DataWriter _this - the DDS_DataWriter object on which the

operation is operated.inout DDS_LivelinessLostStatus *status - the contents of the

DDS_LivelinessLostStatus struct of the DDS_DataWriter will be copiedinto the location specified by status.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:DDS_RETCODE_OK , DDS_RETCODE_ERROR , DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation obtains the DDS_LivelinessLostStatus struct of theDDS_DataWriter. This struct contains the information whether the liveliness (thatthe DDS_DataWriter has committed through its DDS_LivelinessQosPolicy)was respected.This means that the status represents whether the DDS_DataWriter failed toactively signal its liveliness within the offered liveliness period. If the liveliness islost, the DDS_DataReader objects will consider the DDS_DataWriter as nolonger “alive”.The DDS_LivelinessLostStatus can a l so be moni tored us ing aDDS_DataWriterListener or by using the associated DDS_StatusCondition.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the current DDS_LivelinessLostStatus of thisDDS_DataWriter has successfully been copied into the specified statusparameter.

• DDS_RETCODE_ERROR - an internal error has occurred.

325API Reference

3 DCPS Classes and Operations 3.4 Publication Module

• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on aninappropriate object.

• DDS_RETCODE_ALREADY_DELETED - the DDS_DataWriter has already beendeleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

3.4.2.9 DDS_DataWriter_get_matched_subscription_data

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataWriter_get_matched_subscription_data (DDS_DataWriter _this, DDS_SubscriptionBuiltinTopicData *subscription_data, const DDS_InstanceHandle_t subscription_handle);

DescriptionThis operation retrieves information on the specified subscription that is currently“associated” with the DDS_DataWriter.

Parametersin DDS_DataWriter _this - the DDS_DataWriter object on which the

operation is operated.inout DDS_SubscriptionBuiltinTopicData *subscription_data - a

pointer to the sample in which the information about the specified subscriptionis to be stored.

in const DDS_InstanceHandle_t subscription_handle - a handle to thesubscription whose information needs to be retrieved.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:DDS_RETCODE_OK , DDS_RETCODE_ERROR , DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_UNSUPPORTED, DDS_RETCODE_ALREADY_DELETED,DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_NOT_ENABLED.

Detailed DescriptionThis operation retrieves information on the specified subscription that is currently“associated” with the DDS_DataWriter. That is, a subscription with a matchingTopic and compatible QoS that the application has not indicated should be“ignored” by means of the DDS_DomainParticipant_ignore_subscriptionoperation.

326API Reference

3 DCPS Classes and Operations 3.4 Publication Module

The subscription_handle must correspond to a subscription currentlyassociated with the DDS_DataWriter, otherwise the operation will fail and returnDDS_RETCODE_BAD_PARAMETER . The operat ion DDS_DataWriter_get_matched_subscriptions can be used to find the subscriptions that arecurrently matched with the DDS_DataWriter.The operation may also fail if the infrastructure does not hold the informationnecessary to fill in the subscription_data. This is the case when OpenSplice isconfigured not to maintain discovery information in the Networking Service. (Seealso the description of the NetworkService/Discovery[@enabled]attribute in section 4.4.1.6.1 on page 244 of the Deployment Guide.) In thiscase the operation will return DDS_RETCODE_UNSUPPORTED.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the information on the specified subscription has been

successfully retrieved.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_UNSUPPORTED - OpenSplice is configured not to maintain the

information about “associated” subscriptions.• DDS_RETCODE_ALREADY_DELETED - the DDS_DataWriter has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_NOT_ENABLED - the DDS_DataWriter is not enabled.

3.4.2.10 DDS_DataWriter_get_matched_subscriptions

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataWriter_get_matched_subscriptions (DDS_DataWriter _this, DDS_InstanceHandleSeq *subscription_handles);

DescriptionThis operation retrieves the list of subscriptions currently "associated" with theDDS_DataWriter.

327API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Parametersin DDS_DataWriter _this - the DDS_DataWriter object on which the

operation is operated.inout DDS_InstanceHandleSeq *subscription_handles - a sequence

which is used to pass the list of all associated subscribtions.

Return ValueDDS_ReturnCode_t - Poss ib le re turn codes of the opera t ion are :DDS_RETCODE_OK , DDS_RETCODE_ERROR , DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_UNSUPPORTED, DDS_RETCODE_ALREADY_DELETED,DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_NOT_ENABLED.

Detailed DescriptionThis operation retrieves the list of subscriptions currently "associated" with theDDS_DataWriter. That is, subscriptions that have a matching Topic andcompatible QoS that the application has not indicated should be “ignored” by meansof the DDS_DomainParticipant_ignore_subscription operation.The subscription_handles sequence and its buffer may be pre-allocated by theapplication and therefore must either be re-used in a subsequent invocation of theDDS_DataWriter_get_matched_subscriptions operation or be released bycalling DDS_free on the returned subscription_handles. If the pre-allocatedsequence is not big enough to hold the number of associated subscriptions, thesequence will automatically be (re-)allocated to fit the required size. The handles returned in the subscription_handles sequence are the ones thatare used by the DDS implementation to locally identify the corresponding matchedDataReader entities. You can access more detailed information about a particularsubsc r ip t ion by pass ing i t s subscription_handle t o e i t he r t heDDS_DataWriter_get_matched_subscription_data operation or to theDDS_SubscriptionBuiltinTopicDataDataReader_read_instanceoperation on the built-in reader for the “DCPSSubscription” topic. Be aware that since DDS_InstanceHandle_t is an opaque datatype, it does notnecessarily mean that the handles obtained from the DDS_DataWriter_get_matched_subscriptions operation have the same value as the ones thatappear in the instance_handle field of the DDS_SampleInfo when retrievingthe subscription info through corresponding "DCPSSubscriptions" built-in reader.You can’t just compare two handles to determine whether they represent the samesubscription. If you want to know whether two handles actually do represent thesame subscr ipt ion, use both handles to re t r ieve their correspondingDDS_SubscriptionBuiltinTopicData samples and then compare the key fieldof both samples.

328API Reference

3 DCPS Classes and Operations 3.4 Publication Module

The operation may fail if the infrastructure does not locally maintain theconnectivity information. This is the case when OpenSplice is configured not tomaintain discovery information in the Networking Service. (See also the descriptionof the NetworkService/Discovery[@enabled] attribute in section4.4.1.6.1 on page 244 of the Deployment Guide.) In this case the operation willreturn DDS_RETCODE_UNSUPPORTED.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the list of associated subscriptions has successfully been

obtained.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_UNSUPPORTED - OpenSplice is configured not to maintain the

information about “associated” subscriptions.• DDS_RETCODE_ALREADY_DELETED - the DDS_DataWriter has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_NOT_ENABLED - the DDS_DataWriter is not enabled.

3.4.2.11 DDS_DataWriter_get_offered_deadline_missed_status

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataWriter_get_offered_deadline_missed_status (DDS_DataWriter _this, DDS_OfferedDeadlineMissedStatus *status);

DescriptionThis operation obtains the DDS_OfferedDeadlineMissedStatus struct of theDDS_DataWriter.

Parametersin DDS_DataWriter _this - the DDS_DataWriter object on which the

operation is operated.

329API Reference

3 DCPS Classes and Operations 3.4 Publication Module

inout DDS_OfferedDeadlineMissedStatus *status - the contents of theDDS_OfferedDeadlineMissedStatus struct of the DDS_DataWriter willbe copied into the location specified by status.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:DDS_RETCODE_OK , DDS_RETCODE_ERROR , DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation obtains the DDS_OfferedDeadlineMissedStatus struct of theDDS_DataWriter. This struct contains the information whether the deadline (thatthe DDS_DataWriter has committed through its DDS_DeadlineQosPolicy) wasrespected for each instance.The DDS_OfferedDeadlineMissedStatus can also be monitored using aDDS_DataWriterListener or by using the associated DDS_StatusCondition.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the current DDS_LivelinessLostStatus of thisDDS_DataWriter has successfully been copied into the specified statusparameter.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_DataWriter has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

3.4.2.12 DDS_DataWriter_get_offered_incompatible_qos_status

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataWriter_get_offered_incompatible_qos_status (DDS_DataWriter _this, DDS_OfferedIncompatibleQosStatus *status);

330API Reference

3 DCPS Classes and Operations 3.4 Publication Module

DescriptionThis operation obtains the DDS_OfferedIncompatibleQosStatus struct of theDDS_DataWriter.

Parametersin DDS_DataWriter _this - the DDS_DataWriter object on which the

operation is operated.inout DDS_OfferedIncompatibleQosStatus *status - the contents of the

DDS_OfferedIncompatibleQosStatus struct of the DDS_DataWriterwill be copied into the location specified by status.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:DDS_RETCODE_OK , DDS_RETCODE_ERROR , DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation obtains the DDS_OfferedIncompatibleQosStatus struct of theDDS_DataWriter. This struct contains the information whether a QosPolicysetting was incompatible with the requested QosPolicy setting.This means that the status represents whether a DDS_DataReader object has beendiscovered by the DDS_DataWriter with the same DDS_Topic and a requestedDDS_DataReaderQos that was incompatible with the one offered by theDDS_DataWriter.The DDS_OfferedIncompatibleQosStatus can also be monitored using aDDS_DataWriterListener or by using the associated DDS_StatusCondition.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the current DDS_OfferedIncompatibleQosStatus of

this DDS_DataWriter has successfully been copied into the specified statusparameter.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_DataWriter has already been

deleted.

331API Reference

3 DCPS Classes and Operations 3.4 Publication Module

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

3.4.2.13 DDS_DataWriter_get_publication_matched_status

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataWriter_get_publication_matched_status (DDS_DataWriter _this, DDS_PublicationMatchedStatus *status);

DescriptionThis operation obtains the DDS_PublicationMatchedStatus struct of theDDS_DataWriter.

Parametersin DDS_DataWriter _this - the DDS_DataWriter object on which the

operation is operated.inout DDS_PublicationMatchedStatus *status - the contents of the

DDS_PublicationMatchedStatus struct of the DDS_DataWriter will becopied into the location specified by status.

Return ValueDDS_ReturnCode_t - Poss ib le re turn codes of the opera t ion are :DDS_RETCODE_OK , DDS_RETCODE_ERROR , DDS_RETCODE_ILLEGAL_OPERATION, RETCODE_UNSUPPORTED, DDS_RETCODE_ALREADY_DELETED orDDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation obtains the DDS_PublicationMatchedStatus struct of theDDS_DataWriter. This struct contains information about whether a new match hasbeen discovered for the current publication, or whether an existing match has ceasedto exist.This means that the status represents that either a DataReader object has beendiscovered by the DDS_DataWriter with the same Topic and a compatible Qos, orthat a previously-discovered DataReader has ceased to be matched to the currentDDS_DataWriter. A DataReader may cease to match when it gets deleted, when itchanges its Qos to a value that is incompatible with the current DDS_DataWriteror when either the DDS_DataWriter or the DataReader has chosen to put its

332API Reference

3 DCPS Classes and Operations 3.4 Publication Module

matching counterpart on its ignore-list using the DDS_DomainParticipant_ignore_subcription or DDS_DomainParticipant_ignore_publicationoperations.The operation may fail if the infrastructure does not hold the information necessaryto fill in the DDS_PublicationMatchedStatus. This is the case whenOpenSplice is configured not to maintain discovery information in the NetworkingS e r v i c e . ( S e e t h e d e s c r i p t i o n f o r t h e NetworkingService/Discovery/enabled property in the Deployment Manual for more informationa b o u t t h i s s u b j e c t . ) I n t h i s c a s e t h e o p e ra t i o n w i l l r e t u r nDDS_RETCODE_UNSUPPORTED.The DDS_PublicationMatchedStatus can also be monitored using aDDS_DataWriterListener or by using the associated DDS_StatusCondition.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the current DDS_PublicationMatchedStatus of thisDDS_DataWriter has successfully been copied into the specified statusparameter.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_UNSUPPORTED - OpenSplice is configured not to maintain the

information about “associated” subscriptions.• DDS_RETCODE_ALREADY_DELETED - the DDS_DataWriter has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

3.4.2.14 DDS_DataWriter_get_publisher

Synopsis#include <dds_dcps.h>DDS_Publisher DDS_DataWriter_get_publisher (DDS_DataWriter _this);

DescriptionThis operation returns the DDS_Publisher to which the DDS_DataWriterbelongs.

333API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Parametersin DDS_DataWriter _this - the DDS_DataWriter object on which the

operation is operated.

Return ValueDDS_Publisher - a po in te r t o the DDS_Publisher t o wh ich the

DDS_DataWriter belongs.

Detailed DescriptionThis operation returns the DDS_Publisher to which the DDS_DataWriterbelongs, thus the DDS_Publisher that has created the DDS_DataWriter. If theDDS_DataWriter is already deleted, the DDS_OBJECT_NIL pointer is returned.

3.4.2.15 DDS_DataWriter_get_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataWriter_get_qos (DDS_DataWriter _this, DDS_DataWriterQos *qos);

DescriptionThis operation allows access to the existing list of QosPolicy settings for aDDS_DataWriter.

Parametersin DDS_DataWriter _this - the DDS_DataWriter object on which the

operation is operated.inout DDS_DataWriterQos *qos - a po in te r to the des t ina t ion

DDS_DataWriterQos struct in which the QosPolicy settings will be copied.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:DDS_RETCODE_OK , DDS_RETCODE_ERROR , DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation allows access to the existing list of QosPolicy settings of aDDS_DataWriter on which this operation is used. This DDS_DataWriterQos isstored at the location pointed to by the qos parameter.

334API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the existing set of QoS policy values applied to thisDDS_DataWriter has successfully been copied into the specifiedDDS_DataWriterQos parameter.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_DataWriter has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

3.4.2.16 DDS_DataWriter_get_status_changes (inherited)This operation is inherited and therefore not described here. See the classDDS_Entity for further explanation.

Synopsis#include <dds_dcps.h>DDS_StatusMask DDS_DataWriter_get_status_changes (DDS_DataWriter _this);

3.4.2.17 DDS_DataWriter_get_statuscondition (inherited)This operation is inherited and therefore not described here. See the classDDS_Entity for further explanation.

Synopsis#include <dds_dcps.h>DDS_StatusCondition DDS_DataWriter_get_statuscondition (DDS_DataWriter _this);

3.4.2.18 DDS_DataWriter_get_topic

Synopsis#include <dds_dcps.h>DDS_Topic DDS_DataWriter_get_topic (DDS_DataWriter _this);

335API Reference

3 DCPS Classes and Operations 3.4 Publication Module

DescriptionThis operat ion re turns the DDS_Topic which is associated wi th theDDS_DataWriter.

Parametersin DDS_DataWriter _this - the DDS_DataWriter object on which the

operation is operated.

Return ValueDDS_Topic - Return value is a pointer to the DDS_Topic which is associated with

the DDS_DataWriter.

Detailed DescriptionThis operat ion re turns the DDS_Topic which is associated wi th theDDS_DataWriter, thus the DDS_Topic with which the DDS_DataWriter iscreated. If the DDS_DataWriter is already deleted, the DDS_OBJECT_NIL pointeris returned.

3.4.2.19 DDS_DataWriter_lookup_instance (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataWriter class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataWriter class.

Synopsis#include <dds_dcps.h>DDS_InstanceHandle_t DDS_DataWriter_lookup_instance (DDS_DataWriter _this,

<data> *instance_data);

3.4.2.20 DDS_DataWriter_register_instance (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataWriter class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataWriter class.

Synopsis#include <dds_dcps.h>const DDS_InstanceHandle_t

336API Reference

3 DCPS Classes and Operations 3.4 Publication Module

DDS_DataWriter_register_instance (DDS_DataWriter _this,

const <data> *instance_data);

3.4.2.21 DDS_DataWriter_register_instance_w_timestamp (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataWriter class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataWriter class.

Synopsis#include <dds_dcps.h>const DDS_InstanceHandle_t

DDS_DataWriter_register_instance_w_timestamp (DDS_DataWriter _this,

const <data> *instance_data, const DDS_Time_t *source_timestamp);

3.4.2.22 DDS_DataWriter_set_listener

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataWriter_set_listener (DDS_DataWriter _this, const struct DDS_DataWriterListener *a_listener, const DDS_StatusMask mask);

DescriptionThis operation attaches a DDS_DataWriterListener to the DDS_DataWriter.

Parametersin DDS_DataWriter _this - the DDS_DataWriter object on which the

operation is operated.in const struct DDS_DataWriterListener *a_listener - a pointer to

the DDS_DataWriterListener instance, which will be attached to theDDS_DataWriter.

in const DDS_StatusMask mask - a bit-mask in which each bit enables theinvocation of the DDS_DataWriterListener for a certain status.

337API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_UNSUPPORTED , DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation attaches a DDS_DataWriterListener to the DDS_DataWriter.Only one DDS_DataWriterListener can be attached to each DDS_DataWriter.If a DDS_DataWriterListener was already attached, the operation will replace itwith the new one. When a_listener is the DDS_OBJECT_NIL pointer, itrepresents a listener that is treated as a NOOP1 for all statuses activated in thebitmask.

Communication StatusFor each communication status, the StatusChangedFlag flag is initially set toFALSE. It becomes TRUE whenever that communication status changes. For eachco m m un ica t i on s t a t u s a c t i va t ed i n t he mask , t h e a s soc i a t e dDDS_DataWriterListener operation is invoked and the communication status isreset to FALSE, as the listener implicitly accesses the status which is passed as aparameter to that operation. The status is reset prior to calling the listener, so if theapplication calls the get_<status_name>_status from inside the listener it willsee the status already reset. An exception to this rule is the DDS_OBJECT_NILlistener, which does not reset the communication statuses for which it is invoked.The following statuses are applicable to the DDS_DataWriterListener:• DDS_OFFERED_DEADLINE_MISSED_STATUS

• DDS_OFFERED_INCOMPATIBLE_QOS_STATUS

• DDS_LIVELINESS_LOST_STATUS

• DDS_PUBLICATION_MATCHED_STATUS.

Be aware that the DDS_PUBLICATION_MATCHED_STATUS is not applicable whenthe infrastructure does not have the information available to determine connectivity.This is the case when OpenSplice is configured not to maintain discoveryinformation in the Networking Service. (See also the description of theNetworkService/Discovery[@enabled] attribute in section 4.4.1.6.1on page 244 of the Deployment Guide.) In this case the operation will returnDDS_RETCODE_UNSUPPORTED.

1. Short for No-Operation, an instruction that peforms nothing at all.

338API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Status bits are declared as a constant and can be used by the application in an ORoperation to create a tailored mask. The special constant DDS_STATUS_MASK_NONEcan be used to indicate that the created entity should not respond to any of itsavailable statuses. The DDS will therefore attempt to propagate these statuses to itsfactory. The special constant STATUS_MASK_ANY_V1_2 can be used to select allapplicable statuses specified in the “Data Distribution Service for Real-timeSystems Version 1.2” specification.

Status PropagationIn case a communica t ion s ta tus i s not ac t iva ted in the mask o f theDDS_DataWriterListener, the DDS_PublisherListener of the containingDDS_Publisher is invoked (if attached and activated for the status that occurred).T h i s a l l o w s t h e a p p l i c a t i o n to s e t a d e f au l t be hav i ou r i n t h eDDS_PublisherListener of the containing DDS_Publisher and aDDS_DataWriter specific behaviour when needed. In case the communicationstatus is not activated in the mask of the DDS_PublisherListener as well, thec o m m u n i c a t i o n s t a t u s w i l l b e p r o p a g a t e d t o t h eDDS_DomainParticipantListener o f t h e c o n t a i n i n gDDS_DomainParticipant. In case the DDS_DomainParticipantListener isalso not attached or the communication status is not activated in its mask, theapplication is not notified of the change.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the DDS_DataWriterListener is attached.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_UNSUPPORTED - a status was selected that cannot be supported

because the infrastructure does not maintain the required connectivityinformation.

• DDS_RETCODE_ALREADY_DELETED - the DDS_DataWriter has already beendeleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

3.4.2.23 DDS_DataWriter_set_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t

339API Reference

3 DCPS Classes and Operations 3.4 Publication Module

DDS_DataWriter_set_qos (DDS_DataWriter _this, const DDS_DataWriterQos *qos);

DescriptionThis operation replaces the exist ing set of QosPolicy set t ings for aDDS_DataWriter.

Parametersin DDS_DataWriter _this - the DDS_DataWriter object on which the

operation is operated.in const DDS_DataWriterQos *qos - contain the new set of QosPolicy

settings for the DDS_DataWriter.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_UNSUPPORTED, DDS_RETCODE_ALLREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES , DDS_RETCODE_IMMUTABLE_POLICY orDDS_RETCODE_INCONSISTENT_POLICY.

Detailed DescriptionThis operation replaces the exist ing set of QosPolicy set t ings for aDDS_DataWriter. The parameter qos contains the struct with the QosPolicysettings which is checked for self-consistency and mutability. When the applicationtries to change a QosPolicy setting for an enabled DDS_DataWriter, which canonly be set before the DDS_DataWriter is enabled, the operation will fail and aDDS_RETCODE_IMMUTABLE_POLICY is returned. In other words, the applicationmust provide the presently set QosPolicy settings in case of the immutableQosPolicy settings. Only the mutable QosPolicy settings can be changed. Whenqos contains conflicting QosPolicy settings (not self-consistent), the operationwill fail and a DDS_RETCODE_INCONSISTENT_POLICY is returned.The set of QosPolicy settings specified by the qos parameter are applied on top ofthe existing QoS, replacing the values of any policies previously set (provided, theoperation returned DDS_RETCODE_OK).

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the new default DDS_DataWriterQos is set.• DDS_RETCODE_ERROR - an internal error has occurred.

340API Reference

3 DCPS Classes and Operations 3.4 Publication Module

• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on aninappropriate object.

• DDS_RETCODE_BAD_PARAMETER - the parameter qos is not a valid.DDS_DataWriterQos. It contains a QosPolicy setting with an invalidDDS_Duration_t value, an enum value that is outside its legal boundaries or asequence that has inconsistent memory settings.

• DDS_RETCODE_UNSUPPORTED - one or more of the selected QosPolicy values arecurrently not supported by OpenSplice.

• DDS_RETCODE_ALREADY_DELETED - the DDS_DataWriter has already beendeleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_IMMUTABLE_POLICY - the parameter qos contains animmutable QosPolicy setting with a different value than set during enabling ofthe DDS_DataWriter.

• DDS_RETCODE_INCONSISTENT_POLICY - the parameter qos containsconflicting QosPolicy settings, e.g. a history depth that is higher than thespecified resource limits.

3.4.2.24 DDS_DataWriter_unregister_instance (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataWriter class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataWriter class.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataWriter_unregister_instance (DDS_DataWriter _this,

const <data> *instance_data, const DDS_InstanceHandle_t handle);

3.4.2.25 DDS_DataWriter_unregister_instance_w_timestamp (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataWriter class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataWriter class.

341API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataWriter_unregister_instance_w_timestamp (DDS_DataWriter _this,

const <data> *instance_data, const DDS_InstanceHandle_t handle, const DDS_Time_t *source_timestamp);

3.4.2.26 DDS_DataWriter_wait_for_acknowledgments

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataWriter_wait_for_acknowledgments (DDS_DataWriter _this, const DDS_Duration_t *max_wait);

DescriptionThis operation blocks the calling thread until either all data written by theDDS_DataWriter is acknowledged by the local infrastructure, or until the durationspecified by max_wait parameter elapses, whichever happens first.

Parametersin DDS_DataWriter _this - the DDS_DataWriter object on which the

operation is operated.in const DDS_Duration_t *max_wait - the maximum duration to block for

the DDS_DataWriter_wait_for_acknowledgments, after which theap p l i ca t i on t h r ea d i s un b lo cke d . The sp ec i a l c ons t a n tDDS_DURATION_INFINITE can be used when the maximum waiting time doesnot need to be bounded.

Return ValueDDS_ReturnCode_t - Poss ib le re turn codes of the opera t ion are :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_ALREADY_DELETED , DDS_RETCODE_OUT_OF_RESOURCES , DDS_RETCODE_NOT_ENABLED o rDDS_RETCODE_TIMEOUT.

Detailed DescriptionThis operation blocks the calling thread until either all data written by theDDS_DataWriter is acknowledged by the local infrastructure, or until the durationspecified by max_wait parameter elapses, whichever happens first.

342API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Data is acknowledged by the local infrastructure when it does not need to be storedin its DataWriter’s local history. When a locally-connected subscription (includingthe networking service) has no more resources to store incoming samples it will startto reject these samples, resulting in its source DataWriter to store them temporarilyin its own local history to be retransmitted at a later moment in time. In suchscenarios, the DDS_DataWriter_wait_for_acknowledgments operation willblock until the DDS_DataWriter has retransmitted its entire history, which istherefore effectively empty, or until the max_wait timeout expires, whicheverhappens first. In the first case the operation will return DDS_RETCODE_OK, in thelatter it will return DDS_RETCODE_TIMEOUT.Be aware that in case the operation returns DDS_RETCODE_OK, the data has onlybeen acknowledged by the local infrastructure: it does not mean all remotesubscriptions have already received the data. However, delivering the data to remotenodes is then the sole responsibility of the networking service: even when thepublishing application would terminate, all data that has not yet been received maybe considered ‘on-route’ and will therefore eventually arrive (unless the networkingservice itself crashes). In contrast, if the DDS_DataWriter would still have data init’s local history buffer when it terminates, this data is considered ‘lost’. This operation is intended to be used only if the DDS_DataWriter has itsDDS_ReliabilityQosPolicyKind set to DDS_RELIABLE_RELIABILITY_QOS.Otherwise the operation will return immediately with DDS_RETCODE_OK, sincebest-effort DataWriters will never store rejected samples in their local history: theywill just drop them and continue business as usual.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the data of the DDS_DataWriter has been acknowledged

by the local infrastructure.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_DataWriter has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_NOT_ENABLED - the DDS_DataWriter is not enabled.• DDS_RETCODE_TIMEOUT - not all data is acknowledged before max_wait

elapsed.

343API Reference

3 DCPS Classes and Operations 3.4 Publication Module

3.4.2.27 DDS_DataWriter_write (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataWriter class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataWriter class.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t

DDS_DataWriter_write (DDS_DataWriter _this,

const <data> *instance_data, const DDS_InstanceHandle_t handle);

3.4.2.28 DDS_DataWriter_write_w_timestamp (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataWriter class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataWriter class.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t

DDS_DataWriter_write_w_timestamp (DDS_DataWriter _this,

const <data> *instance_data, const DDS_InstanceHandle_t handle, const DDS_Time_t *source_timestamp);

3.4.2.29 DDS_DataWriter_writedispose (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataWriter class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataWriter class.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataWriter_writedispose (DDS_DataWriter _this,

const <data> *instance_data,

344API Reference

3 DCPS Classes and Operations 3.4 Publication Module

const DDS_InstanceHandle_t instance_handle);

3.4.2.30 DDS_DataWriter_writedispose_w_timestamp (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataWriter class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataWriter class.

Synopsis#include <dds_dcps.h>

DDS_ReturnCode_t DDS_DataWriter_writedispose_w_timestamp

(DDS_DataWriter _this, const <data> *instance_data, const DDS_InstanceHandle_t instance_handle, const DDS_Time_t *source_timestamp);

3.4.2.31 Class SPACE_FooDataWriterThe pre-processor generates from IDL type descriptions the application<NameSpace>_<type>DataWriter classes. For each application data type that isused as DDS_Topic data type, a typed class <NameSpace>_<type>DataWriteris derived from the DDS_DataWriter class. In this paragraph, the classSPACE_FooDataWriter descr ibes the opera t ions of these der ived<NameSpace>_<type>DataWriter classes as an example for the fictionalapplication type Foo (defined in the module SPACE).For instance, for an application, the definitions are located in the Space.idl file.The pre-processor will generate a Space.h include file.A SPACE_FooDataWriter is attached to exactly one DDS_Publisher which actsas a factory for it. The SPACE_FooDataWriter is bound to exactly oneDDS_Topic that has been registered to use a data type Foo (defined in the moduleSPACE). The DDS_Topic must exist prior to the SPACE_FooDataWriter creation.The interface description of this class is as follows:

/* * interface SPACE_FooDataWriter *//* * inherited from class DDS_Entity *//* DDS_StatusCondition * SPACE_FooDataWriter_get_statuscondition * (SPACE_FooDataWriter _this); *//* DDS_StatusMask

345API Reference

3 DCPS Classes and Operations 3.4 Publication Module

* SPACE_FooDataWriter_get_status_changes * (SPACE_FooDataWriter _this); *//* DDS_ReturnCode_t * SPACE_FooDataWriter_enable * (SPACE_FooDataWriter _this); *//* * inherited from class DDS_DataWriter *//* DDS_ReturnCode_t * SPACE_FooDataWriter_set_qos * (SPACE_FooDataWriter _this, * const DDS_DataWriterQos *qos); */

/* DDS_ReturnCode_t * SPACE_FooDataWriter_get_qos * (SPACE_FooDataWriter _this, * SPACE_FooDataWriterQos *qos); */

/* DDS_ReturnCode_t * SPACE_FooDataWriter_set_listener * (SPACE_FooDataWriter _this, * const struct DDS_DataWriterListener *a_listener, * const DDS_StatusMask mask); */

/* struct SPACE_FooDataWriterListener * SPACE_FooDataWriter_get_listener * (SPACE_FooDataWriter _this); */

/* DDS_Topic * SPACE_FooDataWriter_get_topic * (SPACE_FooDataWriter _this); */

/* DDS_Publisher * SPACE_FooDataWriter_get_publisher * (SPACE_FooDataWriter _this); */

/* DDS_ReturnCode_t * SPACE_FooDataWriter_wait_for_acknowledgments * (DDS_DataWriter _this, * const DDS_Duration_t *max_wait); */

346API Reference

3 DCPS Classes and Operations 3.4 Publication Module

/* DDS_ReturnCode_t * SPACE_FooDataWriter_get_liveliness_lost_status * (SPACE_FooDataWriter _this, * DDS_LivelinessLostStatus *status); */

/* DDS_ReturnCode_t * SPACE_FooDataWriter_get_offered_deadline_missed_status * (SPACE_FooDataWriter _this, * DDS_OfferedDeadlineMissedStatus *status); */

/* DDS_ReturnCode_t * SPACE_FooDataWriter_get_offered_incompatible_qos_status * (SPACE_FooDataWriter _this, * DDS_OfferedIncompatibleQosStatus *status); */

/* DDS_ReturnCode_t * SPACE_FooDataWriter_get_publication_matched_status * (SPACE_FooDataWriter _this, * DDS_PublicationMatchedStatus *status); */

/* DDS_ReturnCode_t * SPACE_FooDataWriter_assert_liveliness * (SPACE_FooDataWriter _this); */

/* DDS_ReturnCode_t * SPACE_FooDataWriter_get_matched_subscriptions * (SPACE_FooDataWriter _this, * DDS_InstanceHandleSeq *subscription_handles); */

/* DDS_ReturnCode_t * SPACE_FooDataWriter_get_matched_subscription_data * (SPACE_FooDataWriter _this, * DDS_SubscriptionBuiltinTopicData *subscription_data, * const DDS_InstanceHandle_t subscription_handle); *//* * implemented API operations */

DDS_InstanceHandle_t SPACE_FooDataWriter_register_instance (SPACE_FooDataWriter _this, const Foo *instance_data);DDS_InstanceHandle_t SPACE_FooDataWriter_register_instance_w_timestamp

347API Reference

3 DCPS Classes and Operations 3.4 Publication Module

(SPACE_FooDataWriter _this, const Foo *instance_data, const DDS_Time_t *source_timestamp);DDS_ReturnCode_t SPACE_FooDataWriter_unregister_instance (SPACE_FooDataWriter _this, const Foo *instance_data, const DDS_InstanceHandle_t handle);DDS_ReturnCode_t SPACE_FooDataWriter_unregister_instance_w_timestamp (SPACE_FooDataWriter _this, const Foo *instance_data, const DDS_InstanceHandle_t handle, const DDS_Time_t *source_timestamp);DDS_ReturnCode_t SPACE_FooDataWriter_write (SPACE_FooDataWriter _this, const Foo *instance_data, const DDS_InstanceHandle_t handle);DDS_ReturnCode_t SPACE_FooDataWriter_write_w_timestamp (SPACE_FooDataWriter _this, const Foo *instance_data, const DDS_InstanceHandle_t handle, const DDS_Time_t *source_timestamp);DDS_ReturnCode_t SPACE_FooDataWriter_dispose (SPACE_FooDataWriter _this, const Foo *instance_data, const DDS_InstanceHandle_t instance_handle);DDS_ReturnCode_t SPACE_FooDataWriter_dispose_w_timestamp (SPACE_FooDataWriter _this, const Foo *instance_data, const DDS_InstanceHandle_t instance_handle, const DDS_Time_t *source_timestamp);DDS_ReturnCode_t SPACE_FooDataWriter_writedispose

(SPACE_FooDataWriter _this, const Foo *instance_data, const DDS_InstanceHandle_t instance_handle);DDS_ReturnCode_t SPACE_FooDataWriter_writedispose_w_timestamp

(SPACE_FooDataWriter _this, const Foo *instance_data, const DDS_InstanceHandle_t instance_handle,

const DDS_Time_t *source_timestamp);DDS_ReturnCode_t SPACE_FooDataWriter_get_key_value (SPACE_FooDataWriter _this,

348API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Foo *key_holder, const DDS_InstanceHandle_t handle);DDS_InstanceHandle_t SPACE_FooDataWriter_lookup_instance (SPACE_FooDataWriter _this, Foo *instance_data);

The next paragraphs describe the usage of all SPACE_FooDataWriter operations.The inherited operations are listed but not fully described because they are notimplemented in this class. The full description of these operations is given in theclasses from which they are inherited.

3.4.2.32 SPACE_FooDataWriter_assert_liveliness (inherited)This operation is inherited and therefore not described here. See the classDDS_DataWriter for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataWriter_assert_liveliness (SPACE_FooDataWriter _this);

3.4.2.33 SPACE_FooDataWriter_dispose

Synopsis#include <Space.h>DDS_ReturnCode_t

SPACE_FooDataWriter_disposeSPACE_FooDataWriter _this, const Foo *instance_data, const DDS_InstanceHandle_t instance_handle);

DescriptionThis operation requests the Data Distribution Service to mark the instance fordeletion.

Parametersin SPACE_FooDataWriter _this - the SPACE_FooDataWriter object on

which the operation is operated.in const Foo *instance_data - the actual instance to be disposed of.in const DDS_InstanceHandle_t instance_handle - the handle to the

instance to be disposed of.

349API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED , DDS_RETCODE_PRECONDITION_NOT_MET o rDDS_RETCODE_TIMEOUT.

Detailed DescriptionThis operation requests the Data Distribution Service to mark the instance fordeletion. Copies of the instance and its corresponding samples, which are stored inevery connected DDS_DataReader and, dependent on the QoSPolicy settings,also in the Transient and Persistent stores, will be marked for deletion by settingtheir DDS_InstanceStateKind to DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE. When this operation is used, the Data Distribution Service will automatically supplythe value of the source_timestamp that is made available to connectedDDS_DataReader objects. This timestamp is important for the interpretation of theDDS_DestinationOrderQosPolicy.As a side effect, this operation asserts liveliness on the DDS_DataWriter itself andon the containing DDS_DomainParticipant.

Effects on DataReadersActual deletion of the instance administration in a connected DDS_DataReaderwill be postponed until the following conditions have been met:• the instance must be unregistered (either implicitly or explicitly) by all connectedDDS_DataWriters that have previously registered it - A DDS_DataWriter can register an instance explicitly by using one of the

special operations SPACE_FooDataWriter_register_instance orSPACE_FooDataWriter_register_instance_w_timestamp.

- A DDS_DataWriter can register an instance implicitly by using the specialconstant DDS_HANDLE_NIL in any of the other DDS_DataWriter operations.

- A DDS_DataWriter can unregister an instance explicitly by using one of thespecial operations SPACE_FooDataWriter_unregister_instance orSPACE_FooDataWriter_unregister_instance_w_timestamp.

- A DDS_DataWriter will unregister all its contained instances implicitly whenit is deleted.

350API Reference

3 DCPS Classes and Operations 3.4 Publication Module

- When a DDS_DataReader detects a loss of liveliness in one of its connectedDDS_DataWriters, it will consider all instances registered by thatDDS_DataWriter as being implicitly unregistered.

• and the application must have consumed all samples belonging to the instance,either implicitly or explicitly. - An application can consume samples explicitly by invoking theSPACE_FooDataReader_take operation, or one of its variants.

- The DDS_DataReader can consume disposed samples implicitly when theautopurge_disposed_samples_delay of the DDS_ReaderDataLifecycleQosPolicy has expired.

The DDS_DataReader may also remove instances that haven’t been disposed first:this happens when the autopurge_nowriter_samples_delay of theDDS_ReaderDataLifecycleQosPolicy has expired after the instance isconsidered unregistered by all connected DDS_DataWriters (i.e. when it has aDDS_InstanceStateKind of DDS_NOT_ALIVE_NO_WRITERS). See also Section3.1.3.15, DDS_ReaderDataLifecycleQosPolicy, on page 99.

Effects on Transient/Persistent StoresActual deletion of the instance administration in the connected Transient andPersistent stores will be postponed until the following conditions have been met:• the instance must be unregistered (either implicitly or explicitly) by all connectedDDS_DataWriters that have previously registered it. (See above.)

• and the period of time specified by the service_cleanup_delay attribute inthe DDS_DurabilityServiceQosPolicy on the DDS_Topic must haveelapsed after the instance is considered unregistered by all connectedDDS_DataWriters.

See also Section 3.1.3.4, DDS_DurabilityServiceQosPolicy, on page 76.

Instance HandleThe DDS_HANDLE_NIL handle va lue can be used for the parameterinstance_handle. This indicates the identity of the instance is automaticallydeduced from the instance_data (by means of the key).If instance_handle is any value other than DDS_HANDLE_NIL, then it mustc o r r e s p o n d t o t h e v a l u e t h a t w a s r e t u r n e d b y e i t h e r t h eSPACE_FooDataWriter_register_instance o pe ra t i o n o r t h eSPACE_FooDataWriter_register_instance_w_timestamp operation whenthe instance (identified by its key) was registered. If there is no correspondence,then the result of the operation is unspecified.

351API Reference

3 DCPS Classes and Operations 3.4 Publication Module

The sample that is passed as instance_data is only used to check for consistencybetween its key values and the supplied instance_handle: the sample itself willnot actually be delivered to the connected DDS_DataReaders. Use theSPACE_FooDataWriter_writedispose operation if the sample itself should bedelivered together with the dispose request.

BlockingIf the DDS_HistoryQosPolicy is set to DDS_KEEP_ALL_HISTORY_QOS, theSPACE_FooDataWriter_dispose operation on the DDS_DataWriter mayblock if the modification would cause data to be lost because one of the limits,specified in the DDS_ResourceLimitsQosPolicy, to be exceeded. Under thesec i r c u m s t a n c e s , t h e max_blocking_time a t t r i b u t e o f t h eReliabilityQosPolicy c o n f i g u r e s t h e m a x i m u m t i m e t h eSPACE_FooDataWriter_dispose operation may block (waiting for space tobecome available). If max_blocking_time elapses before the DDS_DataWriteri s ab le to s to re the modi f ica t ion wi thout exceeding the l imi t s , theSPACE_FooDataWriter_dispose opera t ion wi l l f a i l and re tu rnsDDS_RETCODE_TIMEOUT.

Sample ValidationOpenSplice offers the possibility to check the sample that is passed asinstance_data for validity. Because validity checking might reduce the overallperformance, it is by default disabled. This has been done by enclosing the validitychecking with conditional compiler directives like this:

#ifdef OSPL_BOUNDS_CHECK // check a specific bound.#endif

By defining a macro called OSPL_OSPL_BOUNDS_CHECK, the validity checking willbe included. On most compilers this macro can be defined by passing an additionalcommand line parameter called -DOSPL_BOUNDS_CHECK.Since the SPACE_FooDataWriter_dispose operation only uses the sample tocheck for consistency between its key values and the supplied instance_handle,only those keyfields will be validated against the restrictions imposed by the IDL toC language mapping, where:• an enum may not exceed the value of its highest label• a string (bounded or unbounded) may not be NULL. (Use “” for an empty string

instead)• the length of a bounded string may not exceed the limit specified in IDL

i

352API Reference

3 DCPS Classes and Operations 3.4 Publication Module

If any of these restrictions is violated when validity checking is enabled, then theoperation will fail and return a DDS_RETCODE_BAD_PARAMETER. More specificinformation about the context of this error will be written to the error log. Whenvalidity checking is disabled, any of these violations may result in undefinedbehaviour.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the Data Distribution Service is informed that the instance

data must be disposed of.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - instance_handle is not a valid handle orinstance_data is not a valid sample.

• DDS_RETCODE_ALREADY_DELETED - the SPACE_FooDataWriter has alreadybeen deleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_NOT_ENABLED - the SPACE_FooDataWriter is not enabled.• DDS_RETCODE_PRECONDITION_NOT_MET - the instance_handle has not

been registered with this SPACE_FooDataWriter.• DDS_RETCODE_TIMEOUT - the current action overflowed the available resources

as specified by the combination of the DDS_ReliabilityQosPolicy,DDS_HistoryQosPolicy and DDS_ResourceLimitsQosPolicy. Thiscaused blocking of the SPACE_FooDataWriter_dispose operation, whichcould not be resolved before max_blocking_time of theDDS_ReliabilityQosPolicy elapsed.

3.4.2.34 SPACE_FooDataWriter_dispose_w_timestamp

Synopsis#include <Space.h>

DDS_ReturnCode_t SPACE_FooDataWriter_dispose_w_timestamp

(SPACE_FooDataWriter _this, const Foo *instance_data, const DDS_InstanceHandle_t instance_handle, const DDS_Time_t *source_timestamp);

353API Reference

3 DCPS Classes and Operations 3.4 Publication Module

DescriptionThis operation requests the Data Distribution Service to mark the instance fordeletion and provides a value for the source_timestamp explicitly.

Parametersin SPACE_FooDataWriter _this - the SPACE_FooDataWriter object on

which the operation is operated.in const Foo *instance_data - the actual instance to be disposed of.in const DDS_InstanceHandle_t instance_handle - the handle to the

instance to be disposed of.in const DDS_Time_t *source_timestamp - the timestamp which is

provided for the DDS_DataReader.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED , DDS_RETCODE_PRECONDITION_NOT_MET o rDDS_RETCODE_TIMEOUT.

Detailed DescriptionThis operation performs the same functions as SPACE_FooDataWriter_disposeexcept that the application provides the value for the source_timestamp that ismade available to connected DDS_DataReader objects. This timestamp isimportant for the interpretation of the DDS_DestinationOrderQosPolicy.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the Data Distribution Service is informed that the instance

data must be disposed of.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - instance_handle is not a valid handle orinstance_data is not a valid sample.

• DDS_RETCODE_ALREADY_DELETED - the SPACE_FooDataWriter has alreadybeen deleted.

354API Reference

3 DCPS Classes and Operations 3.4 Publication Module

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_NOT_ENABLED - the SPACE_FooDataWriter is not enabled.• DDS_RETCODE_PRECONDITION_NOT_MET - the instance_handle has not

been registered with this SPACE_FooDataWriter.• DDS_RETCODE_TIMEOUT - the current action overflowed the available resources

as specified by the combination of the DDS_ReliabilityQosPolicy,DDS_HistoryQosPolicy and DDS_ResourceLimitsQosPolicy. Thiscaused blocking of the SPACE_FooDataWriter_dispose_w_timestampoperation, which could not be resolved before max_blocking_time of theDDS_ReliabilityQosPolicy elapsed.

3.4.2.35 SPACE_FooDataWriter_enable (inherited)This operation is inherited and therefore not described here. See the classDDS_Entity for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataWriter_enable (SPACE_FooDataWriter _this);

3.4.2.36 SPACE_FooDataWriter_get_key_value

Synopsis#include <Space.h>DDS_ReturnCode_t

SPACE_FooDataWriter_get_key_value(SPACE_FooDataWriter _this, Foo *key_holder, const DDS_InstanceHandle_t handle);

DescriptionThis operation retrieves the key value of a specific instance.

Parametersin SPACE_FooDataWriter _this - the SPACE_FooDataWriter object on

which the operation is operated.inout Foo *key_holder - the sample in which the key values are stored.in const DDS_InstanceHandle_t handle - the handle to the instance from

which to get the key value.

355API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED or DDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionThis operat ion retr ieves the key value of the instance pointed to byinstance_handle. When the operation is called with an DDS_HANDLE_NILhand l e va lue a s an instance_handle , t he ope ra t i on w i l l r e t u rnDDS_RETCODE_BAD_PARAMETER. The operation will only fill the fields that formthe key inside the key_holder instance. This means that the non-key fields are notapplicable and may contain garbage.The operation must only be called on registered instances. Otherwise the operationreturns the error DDS_RETCODE_PRECONDITION_NOT_MET.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the key_holder instance contains the key values of the

instance.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - handle is not a valid handle or key_holder

is not a valid pointer.• DDS_RETCODE_ALREADY_DELETED - the SPACE_FooDataWriter has already

been deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_NOT_ENABLED - the SPACE_FooDataWriter is not enabled.• DDS_RETCODE_PRECONDITION_NOT_MET - this instance is not registered.

3.4.2.37 SPACE_FooDataWriter_get_listener (inherited)This operation is inherited and therefore not described here. See the classDDS_DataWriter for further explanation.

Synopsis#include <Space.h>

356API Reference

3 DCPS Classes and Operations 3.4 Publication Module

struct SPACE_FooDataWriterListener SPACE_FooDataWriter_get_listener (SPACE_FooDataWriter _this);

3.4.2.38 SPACE_FooDataWriter_get_liveliness_lost_status (inherited)This operation is inherited and therefore not described here. See the classDDS_DataWriter for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataWriter_get_liveliness_lost_status (SPACE_FooDataWriter _this, DDS_LivelinessLostStatus *status);

3.4.2.39 SPACE_FooDataWriter_get_matched_subscription_data (inherited)This operation is inherited and therefore not described here. See the classDDS_DataWriter for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataWriter_get_matched_subscription_data (SPACE_FooDataWriter _this, DDS_SubscriptionBuiltinTopicData *subscription_data, const DDS_InstanceHandle_t subscription_handle);

3.4.2.40 SPACE_FooDataWriter_get_matched_subscriptions (inherited)This operation is inherited and therefore not described here. See the classDDS_DataWriter for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataWriter_get_matched_subscriptions (SPACE_FooDataWriter _this, DDS_InstanceHandleSeq *subscription_handles);

3.4.2.41 SPACE_FooDataWriter_get_offered_deadline_missed_status (inherited)

This operation is inherited and therefore not described here. See the classDDS_DataWriter for further explanation.

Synopsis#include <Space.h>

357API Reference

3 DCPS Classes and Operations 3.4 Publication Module

DDS_ReturnCode_t SPACE_FooDataWriter_get_offered_deadline_missed_status (SPACE_FooDataWriter _this, DDS_OfferedDeadlineMissedStatus *status);

3.4.2.42 SPACE_FooDataWriter_get_offered_incompatible_qos_status (inherited)

This operation is inherited and therefore not described here. See the classDDS_DataWriter for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataWriter_get_offered_incompatible_qos_status (SPACE_FooDataWriter _this, DDS_OfferedIncompatibleQosStatus *status);

3.4.2.43 SPACE_FooDataWriter_get_publication_matched_status (inherited)This operation is inherited and therefore not described here. See the classDDS_DataWriter for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataWriter_get_publication_matched_status (SPACE_FooDataWriter _this, DDS_PublicationMatchedStatus *status);

3.4.2.44 SPACE_FooDataWriter_get_publisher (inherited)This operation is inherited and therefore not described here. See the classDDS_DataWriter for further explanation.

Synopsis#include <Space.h>DDS_Publisher SPACE_FooDataWriter_get_publisher (SPACE_FooDataWriter _this);

3.4.2.45 SPACE_FooDataWriter_get_qos (inherited)This operation is inherited and therefore not described here. See the classDDS_DataWriter for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t

358API Reference

3 DCPS Classes and Operations 3.4 Publication Module

SPACE_FooDataWriter_get_qos (SPACE_FooDataWriter _this, SPACE_FooDataWriterQos *qos);

3.4.2.46 SPACE_FooDataWriter_get_status_changes (inherited)This operation is inherited and therefore not described here. See the classDDS_Entity for further explanation.

Synopsis#include <Space.h>DDS_StatusMask SPACE_FooDataWriter_get_status_changes (SPACE_FooDataWriter _this);

3.4.2.47 SPACE_FooDataWriter_get_statuscondition (inherited)This operation is inherited and therefore not described here. See the classDDS_Entity for further explanation.

Synopsis#include <Space.h>DDS_StatusCondition SPACE_FooDataWriter_get_statuscondition (SPACE_FooDataWriter _this);

3.4.2.48 SPACE_FooDataWriter_get_topic (inherited)This operation is inherited and therefore not described here. See the classDDS_DataWriter for further explanation.

Synopsis#include <Space.h>DDS_Topic SPACE_FooDataWriter_get_topic (SPACE_FooDataWriter _this);

3.4.2.49 SPACE_FooDataWriter_lookup_instance

Synopsis#include <Space.h>DDS_InstanceHandle_t SPACE_FooDataWriter_lookup_instance (SPACE_FooDataWriter _this,

Foo *instance_data);

359API Reference

3 DCPS Classes and Operations 3.4 Publication Module

DescriptionThis operation returns the value of the instance handle which corresponds to theinstance_data.

Parametersin SPACE_FooDataWriter _this - the SPACE_FooDataWriter object on

which the operation is operated.in Foo *instance_data - the instance for which the corresponding instance

handle needs to be looked up.

Return ValueDDS_InstanceHandle_t - Result value is the instance handle which corresponds

to the instance_data.

Detailed DescriptionThis operation returns the value of the instance handle which corresponds to theinstance_data. The instance_data parameter is only used for the purpose ofexamining the fields that define the key. The instance handle can be used in anywrite, dispose or unregister operations (or their timestamped variants) thatoperate on a specific instance. Note that DDS_DataWriter instance handles arelocal, and are not interchangeable with DDS_DataReader instance handles nor withinstance handles of an other DDS_DataWriter.This operation does not register the instance in question. If the instance has not beenpreviously registered, if the DDS_DataWriter is already deleted or if for any otherreason the Service is unable to provide an instance handle, the Service will returnthe special value DDS_HANDLE_NIL.

Sample ValidationOpenSplice offers the possibility to check the sample that is passed asinstance_data for validity. Because validity checking might reduce the overallperformance, it is by default disabled. This has been done by enclosing the validitychecking with conditional compiler directives like this:

#ifdef OSPL_BOUNDS_CHECK // check a specific bound.#endif

By defining a macro called OSPL_OSPL_BOUNDS_CHECK, the validity checking willbe included. On most compilers this macro can be defined by passing an additionalcommand line parameter called -DOSPL_BOUNDS_CHECK.

i

360API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Since the SPACE_FooDataWriter_lookup_instance operation merely uses thesample to determine its identity based on the uniqueness of its key values, only thekeyfields will be validated against the restrictions imposed by the IDL to Clanguage mapping, where:• an enum may not exceed the value of its highest label• a string (bounded or unbounded) may not be NULL. (Use “” for an empty string

instead)• the length of a bounded string may not exceed the limit specified in IDLIf any of these restrictions is violated when validity checking is enabled, then theoperation will fail and return a DDS_HANDLE_NIL. More specific information aboutthe context of this error will be written to the error log. When validity checking isdisabled, any of these violations may result in undefined behaviour.

3.4.2.50 SPACE_FooDataWriter_register_instance

Synopsis#include <Space.h>

DDS_InstanceHandle_t SPACE_FooDataWriter_register_instance

(SPACE_FooDataWriter _this, const Foo *instance_data);

DescriptionThis operation informs the Data Distribution Service that the application will bemodifying a particular instance.

Parametersin SPACE_FooDataWriter _this - the SPACE_FooDataWriter object on

which the operation is operated.in const Foo *instance_data - the new instance, which the application

writes to or disposes of.

Return ValueDDS_InstanceHandle_t - Result value is the handle to the Instance, which may

be used for writing and disposing of. In case of an error, a DDS_HANDLE_NILhandle value is returned.

Detailed DescriptionThis operation informs the Data Distribution Service that the application will bemodifying a particular instance. This operation may be invoked prior to calling anyoperation that modifies the instance, such as SPACE_FooDataWriter_write,

361API Reference

3 DCPS Classes and Operations 3.4 Publication Module

SPACE_FooDataWriter_write_w_timestamp , SPACE_FooDataWriter_unregister_instance, SPACE_FooDataWriter_unregister_instance_w_timestamp , SPACE_FooDataWriter_dispose ,SPACE_FooDataWriter_dispose_w_timestamp, SPACE_FooDataWriter_writedispose and SPACE_FooDataWriter_writedispose_w_timestamp.When the application does register the instance before modifying, the DataDistribution Service will handle the instance more efficiently. It takes as a parameter(instance_data) an instance (to get the key value) and returns a handle that canbe used in successive DDS_DataWriter operations. In case of an error, aDDS_HANDLE_NIL handle value is returned. The explicit use of this operation is optional as the application can directly call theSPACE_FooDataWriter_write , SPACE_FooDataWriter_write_w_timestamp , SPACE_FooDataWriter_unregister_instance,SPACE_FooDataWriter_unregister_instance_w_timestamp,SPACE_FooDataWriter_dispose , SPACE_FooDataWriter_dispose_w_timestamp, SPACE_FooDataWriter_writedispose andSPACE_FooDataWriter_writedispose_w_timestamp operations and specifya DDS_HANDLE_NIL handle value to indicate that the sample should be examinedto identify the instance.When this operation is used, the Data Distribution Service will automatically supplythe value of the source_timestamp that is made available to connectedDDS_DataReader objects. This timestamp is important for the interpretation of theDDS_DestinationOrderQosPolicy.

BlockingIf the DDS_HistoryQosPolicy is set to KEEP_ALL_HISTORY_QOS, theSPACE_FooDataWriter_register_instance ope ra t i on on t heDDS_DataWriter may block if the modification would cause data to be lostbecause one of the limits, specified in the DDS_ResourceLimitsQosPolicy, tobe e xce eded . I n c a se t he synchronous a t t r i b u t e v a l u e o f t h eReliabilityQosPolicy is set to TRUE for communicating DataWriters andDataReaders then the DataWriter wil l wait unti l al l synchronousDataReaders have acknowledged the data. Under these circumstances, themax_blocking_time attribute of the ReliabilityQosPolicy configures themaximum time the SPACE_FooDataWriter_register_instance operationmay block (either waiting for space to become available or data to beacknowledged). If max_blocking_time elapses before the DDS_DataWriter isable to store the modification without exceeding the limits and all expectedacknowledgeme n t s a r e r e ce ive d , t he SPACE_FooDataWriter_register_instance operation will fail and returns DDS_HANDLE_NIL.

362API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Sample ValidationOpenSplice offers the possibility to check the sample that is passed asinstance_data for validity. Because validity checking might reduce the overallperformance, it is by default disabled. This has been done by enclosing the validitychecking with conditional compiler directives like this:

#ifdef OSPL_BOUNDS_CHECK // check a specific bound.#endif

By defining a macro called OSPL_OSPL_BOUNDS_CHECK, the validity checking willbe included. On most compilers this macro can be defined by passing an additionalcommand line parameter called -DOSPL_BOUNDS_CHECK.Since the SPACE_FooDataWriter_register_instance operation merely usesthe sample to determine its identity based on the uniqueness of its key values, onlythe keyfields will be validated against the restrictions imposed by the IDL to Clanguage mapping, where:• an enum may not exceed the value of its highest label• a string (bounded or unbounded) may not be NULL. (Use “” for an empty string

instead)• the length of a bounded string may not exceed the limit specified in IDLIf any of these restrictions is violated when validity checking is enabled, then theoperation will fail and return a DDS_HANDLE_NIL. More specific information aboutthe context of this error will be written to the error log. When validity checking isdisabled, any of these violations may result in undefined behaviour.

Multiple CallsIf this operation is called for an already registered instance, it just returns the alreadyallocated instance handle. This may be used to look up and retrieve the handleallocated to a given instance.

3.4.2.51 SPACE_FooDataWriter_register_instance_w_timestamp

Synopsis#include <Space.h>DDS_InstanceHandle_t

SPACE_FooDataWriter_register_instance_w_timestamp (SPACE_FooDataWriter _this,

const Foo *instance_data, const DDS_Time_t *source_timestamp);

i

363API Reference

3 DCPS Classes and Operations 3.4 Publication Module

DescriptionThis operation will inform the Data Distribution Service that the application will bemodifying a particular instance and provides a value for the source_timestampexplicitly.

Parametersin SPACE_FooDataWriter _this - the SPACE_FooDataWriter object on

which the operation is operated.in Foo *instance_data - the instance, which the application will write to or

dispose of.in const DDS_Time_t *source_timestamp - the timestamp used.

Return ValueDDS_InstanceHandle_t - Result value is the handle to the Instance, which

must be used for writing and disposing. In case of an error, a DDS_HANDLE_NILhandle value is returned.

Detailed DescriptionThi s ope ra t i on pe r fo rms t he s ame func t i ons a sSPACE_FooDataWriter_register_instance except that the applicationprovides the value for the source_timestamp that is made available to connectedDDS_DataReader objects. This timestamp is important for the interpretation of theDDS_DestinationOrderQosPolicy.

Multiple CallsIf this operation is called for an already registered instance, it just returns the alreadyallocated instance handle. This may be used to look up and retrieve the handleallocated to a given instance. The source_timestamp is ignored in that case.

3.4.2.52 SPACE_FooDataWriter_set_listener (inherited)This operation is inherited and therefore not described here. See the classDDS_DataWriter for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataWriter_set_listener (SPACE_FooDataWriter _this, const struct DDS_DataWriterListener *a_listener, const DDS_StatusMask mask);

364API Reference

3 DCPS Classes and Operations 3.4 Publication Module

3.4.2.53 SPACE_FooDataWriter_set_qos (inherited)This operation is inherited and therefore not described here. See the classDDS_DataWriter for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataWriter_set_qos (SPACE_FooDataWriter _this, const DDS_DataWriterQos *qos);

3.4.2.54 SPACE_FooDataWriter_unregister_instance

Synopsis#include <Space.h>DDS_ReturnCode_t

SPACE_FooDataWriter_unregister_instance (SPACE_FooDataWriter _this,

const Foo *instance_data, const DDS_InstanceHandle_t handle);

DescriptionThis operation informs the Data Distribution Service that the application will not bemodifying a particular instance any more.

Parametersin SPACE_FooDataWriter _this - the SPACE_FooDataWriter object on

which the operation is operated.in const Foo *instance_data - the instance to which the application was

writing or disposing.in const DDS_InstanceHandle_t handle - the handle to the instance that

has been used for writing and disposing.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED , DDS_RETCODE_PRECONDITION_NOT_MET o rDDS_RETCODE_TIMEOUT.

365API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Detailed DescriptionThis operation informs the Data Distribution Service that the application will not bemodifying a particular instance any more. Therefore, this operation reverses thea c t i o n o f SPACE_FooDataWriter_register_instance o rSPACE_FooDataWriter_register_instance_w_timestamp. It should onlybe called on an instance that is currently registered. This operation should bec a l l e d j u s t o n c e p e r instance , r e g a r d l e s s o f ho w m a n y t i m e sSPACE_FooDataWriter_register_instance was called for that instance.This operation also indicates that the Data Distribution Service can locally removeall information regarding that instance. The application should not attempt to usethe handle, previously allocated to that instance, after calling this operation.When this operation is used, the Data Distribution Service will automatically supplythe value of the source_timestamp that is made available to connectedDDS_DataReader objects. This timestamp is important for the interpretation of theDDS_DestinationOrderQosPolicy.

EffectsIf, after unregistering, the application wants to modify (write or dispose) theinstance, it first has to register the instance again, or it has to use the specialhandle value DDS_HANDLE_NIL.This operation does not indicate that the instance should be deleted (that is thepurpose of SPACE_FooDataWriter_dispose). This operation just indicates thatthe DDS_DataWriter no longer has “anything to say” about the instance. Ifthere is no other DDS_DataWriter that has registered the instance as well, then theDDS_InstanceStateKind in all connected DDS_DataReaders will be changedto DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE , provided thisDDS_InstanceStateKind w a s n o t a l r e a d y s e t t oDDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE . In the last case theDDS_InstanceStateKind w i l l n o t b e e f f e c t e d b y t h eSPACE_FooDataWriter_unregister_instance call, see also Figure 21:, StateChart of the instance_state for a Single Instance, on page 632.This operation can affect the ownership of the data instance. If theDDS_DataWriter was the exclusive owner of the instance, calling this operationwill release that ownership, meaning ownership may be transferred to another,possibly lower strength, DDS_DataWriter.The operation must be called only on registered instances. Otherwise the operationreturns the error DDS_RETCODE_PRECONDITION_NOT_MET.

366API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Instance HandleThe DDS_HANDLE_NIL handle value can be used for the parameter handle. Thisindicates that the identity of the instance is automatically deduced from theinstance_data (by means of the key).If handle is any value other than DDS_HANDLE_NIL, then it must correspond to thevalue returned by SPACE_FooDataWriter_register_instance orSPACE_FooDataWriter_register_instance_w_timestamp when theinstance (identified by its key) was registered. If there is no correspondence, thenthe result of the operation is unspecified.The sample that is passed as instance_data is used to check for consistencybetween its key values and the supplied instance_handle: the sample itself willnot actually be delivered to the connected DDS_DataReaders.

BlockingIf the DDS_HistoryQosPolicy is set to DDS_KEEP_ALL_HISTORY_QOS, then theSPACE_FooDataWriter_unregister_instance operat ion on theDDS_DataWriter may block if the modification would cause data to be lostbecause one of the limits, specified in the DDS_ResourceLimitsQosPolicy, tobe e xce ede d . I n ca se t he synchronous a t t r i b u t e v a l u e o f t h eReliabilityQosPolicy is set to TRUE for communicating DataWriters andDataReaders then the DataWriter wil l wait unti l al l synchronousDataReaders have acknowledged the data. Under these circumstances, themax_blocking_time attribute of the ReliabilityQosPolicy configures themaximum time the SPACE_FooDataWriter_unregister_instance operationmay block (either waiting for space to become available or data to beacknowledged). If max_blocking_time elapses before the DDS_DataWriter isable to store the modification without exceeding the limits and all expecteda c k n o w l e d g e m e n t s a r e r e c e i v e d , t h eSPACE_FooDataWriter_unregister_instance operation will fail and returnsDDS_RETCODE_TIMEOUT.

Sample ValidationOpenSplice offers the possibility to check the sample that is passed asinstance_data for validity. Because validity checking might reduce the overallperformance, it is by default disabled. This has been done by enclosing the validitychecking with conditional compiler directives like this:

#ifdef OSPL_BOUNDS_CHECK // check a specific bound.#endif

367API Reference

3 DCPS Classes and Operations 3.4 Publication Module

By defining a macro called OSPL_OSPL_BOUNDS_CHECK, the validity checking willbe included. On most compilers this macro can be defined by passing an additionalcommand line parameter called -DOSPL_BOUNDS_CHECK.Since the SPACE_FooDataWriter_unregister_instance operation merelyuses the sample to check for consistency between its key values and the suppliedinstance_handle, only these keyfields will be validated against the restrictionsimposed by the IDL to C language mapping:• an enum may not exceed the value of its highest label.• a string (bounded or unbounded) may not be NULL. (Use “” for an empty string

instead).• the length of a bounded string may not exceed the limit specified in IDL.If any of these restrictions is violated when validity checking is enabled, theoperation will fail and return a DDS_RETCODE_BAD_PARAMETER. More specificinformation about the context of this error will be written to the error log. Whenvalidity checking is disabled, any of these violations may result in undefinedbehaviour.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the Data Distribution Service is informed that the instance

will not be modified any more.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - handle is not a valid handle orinstance_data is not a valid sample.

• DDS_RETCODE_ALREADY_DELETED - the SPACE_FooDataWriter has alreadybeen deleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_NOT_ENABLED - the SPACE_FooDataWriter is not enabled.• DDS_RETCODE_PRECONDITION_NOT_MET - the handle has not been registered

with this SPACE_FooDataWriter.• DDS_RETCODE_TIMEOUT - either the current action overflowed the available

resources as specified by the combination of the DDS_ReliabilityQosPolicy,DDS_HistoryQosPolicy and DDS_ResourceLimitsQosPolicy, or thecurrent action was waiting for data delivery acknowledgement by synchronousDataReaders. This caused blocking of the

i

368API Reference

3 DCPS Classes and Operations 3.4 Publication Module

SPACE_FooDataWriter_unregister_instance_w_timestamp operation,which could not be resolved before max_blocking_time of theDDS_ReliabilityQosPolicy elapsed.

3.4.2.55 SPACE_FooDataWriter_unregister_instance_w_timestamp

Synopsis#include <Space.h>

DDS_ReturnCode_t SPACE_FooDataWriter_unregister_instance_w_timestamp

(SPACE_FooDataWriter _this, const Foo *instance_data, const DDS_InstanceHandle_t handle, const DDS_Time_t *source_timestamp);

DescriptionThis operation will inform the Data Distribution Service that the application will notbe modifying a particular instance any more and provides a value for thesource_timestamp explicitly.

Parametersin SPACE_FooDataWriter _this - the SPACE_FooDataWriter object on

which the operation is operated.in Foo *instance_data - the instance to which the application was writing or

disposing.in const DDS_InstanceHandle_t handle - the handle to the instance that

has been used for writing and disposing.in const DDS_Time_t *source_timestamp - the timestamp used.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED , DDS_RETCODE_PRECONDITION_NOT_MET o rDDS_RETCODE_TIMEOUT.

369API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Detailed DescriptionThi s ope ra t i on pe r fo rms t he s ame func t i ons a sSPACE_FooDataWriter_unregister_instance except that the applicationprovides the value for the source_timestamp that is made available to connectedDDS_DataReader objects. This timestamp is important for the interpretation of theDDS_DestinationOrderQosPolicy.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the Data Distribution Service is informed that the instance

will not be modified any more.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - handle is not a valid handle orinstance_data is not a valid sample.

• DDS_RETCODE_ALREADY_DELETED - the SPACE_FooDataWriter has alreadybeen deleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_NOT_ENABLED - the SPACE_FooDataWriter is not enabled.• DDS_RETCODE_PRECONDITION_NOT_MET - the handle has not been registered

with this SPACE_FooDataWriter.• DDS_RETCODE_TIMEOUT - the current action overflowed the available resources

as specified by the combination of the DDS_ReliabilityQosPolicy,DDS_HistoryQosPolicy and DDS_ResourceLimitsQosPolicy. Thiscaused blocking of the SPACE_FooDataWriter_unregister_instance_w_timestamp operation, which could not be resolved beforemax_blocking_time of the DDS_ReliabilityQosPolicy elapsed.

3.4.2.56 SPACE_FooDataWriter_wait_for_acknowledgments (inherited)This operation is inherited and therefore not described here. See the classDDS_DataWriter for further explanation.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t SPACE_FooDataWriter_wait_for_acknowledgments (SPACE_FooDataWriter _this,

370API Reference

3 DCPS Classes and Operations 3.4 Publication Module

const DDS_Duration_t *max_wait);

3.4.2.57 SPACE_FooDataWriter_write

Synopsis#include <Space.h>

DDS_ReturnCode_t SPACE_FooDataWriter_write

(SPACE_FooDataWriter _this, const Foo *instance_data, const DDS_InstanceHandle_t handle);

DescriptionThis operation modifies the value of a data instance.

Parametersin SPACE_FooDataWriter _this - the SPACE_FooDataWriter object on

which the operation is operated.in const Foo *instance_data - the data to be written.in const DDS_InstanceHandle_t handle - the handle to the instance as

supplied by SPACE_FooDataWriter_register_instance.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED , DDS_RETCODE_PRECONDITION_NOT_MET o rDDS_RETCODE_TIMEOUT.

Detailed DescriptionThis operation modifies the value of a data instance. When this operation is used,the Data Distribution Service will automatically supply the value of thesource_timestamp that is made available to connected DDS_DataReaderob jec t s . Th i s t imes t amp i s impor tan t fo r t he in te rp re ta t ion o f t heDDS_DestinationOrderQosPolicy.As a side effect, this operation asserts liveliness on the DDS_DataWriter itself andon the containing DDS_DomainParticipant.Before writing data to an instance, the instance may be registered with theSPACE_FooDataWriter_register_instance o rSPACE_FooDataWriter_register_instance_w_timestamp operation. Thehandle returned by one of the SPACE_FooDataWriter_register_instance

371API Reference

3 DCPS Classes and Operations 3.4 Publication Module

o p e r a t i o n s c a n b e s u p p l i e d t o t h e p a r a m e t e r handle o f t h eSPACE_FooDataWriter_write operation. However, it is also possible to supplythe special DDS_HANDLE_NIL handle value, which means that the identity of theinstance is automatically deduced from the instance_data (identified by thekey).

Instance HandleThe DDS_HANDLE_NIL handle value can be used for the parameter handle. Thisindicates the identity of the instance is automatically deduced from theinstance_data (by means of the key).If handle is any value other than DDS_HANDLE_NIL, it must correspond to thevalue returned by SPACE_FooDataWriter_register_instance orSPACE_FooDataWriter_register_instance_w_timestamp when theinstance (identified by its key) was registered. Passing such a registered handlehelps the Data Distribution Service to process the sample more efficiently. If there isno correspondence between handle and sample, the result of the operation isunspecified.

BlockingIf the DDS_HistoryQosPolicy is set to DDS_KEEP_ALL_HISTORY_QOS, theSPACE_FooDataWriter_write operation on the DDS_DataWriter may block ifthe modification would cause data to be lost because one of the limits, specified inthe DDS_ResourceLimitsQosPolicy, is exceeded. In case the synchronousattribute value of the ReliabilityQosPolicy is set to TRUE for communicatingDataWriters and DataReaders then the DataWriter will wait until allsynchronous DataReaders have acknowledged the data. Under thesec i r c u m s t a n c e s , t h e max_blocking_time a t t r i b u t e o f t h eReliabilityQosPolicy c o n f i g u r e s t h e m a x i m u m t i m e t h eSPACE_FooDataWriter_write operation may block (either waiting for space tobecome available or data to be acknowledged). If max_blocking_time elapsesbefore the DDS_DataWriter is able to store the modification without exceedingt h e l i m i t s a n d a l l e x p e c t e d a c k n o w l e d g e m e n t s a r e r e c e i v e d , t h eSPACE_FooDataWriter_write o p e r a t i o n w i l l f a i l a n d r e t u r n sDDS_RETCODE_TIMEOUT.

Sample ValidationOpenSplice offers the possibility to check the sample that is passed asinstance_data for validity. Because validity checking might reduce the overallperformance, it is by default disabled. This has been done by enclosing the validitychecking with conditional compiler directives like this:

#ifdef OSPL_BOUNDS_CHECK // check a specific bound.

372API Reference

3 DCPS Classes and Operations 3.4 Publication Module

#endif

By defining a macro called OSPL_OSPL_BOUNDS_CHECK, the validity checking willbe included. On most compilers this macro can be defined by passing an additionalcommand line parameter called -DOSPL_BOUNDS_CHECK.Before the sample is accepted by the DataWriter, it is validated against therestrictions imposed by the IDL to C language mapping:• an enum may not exceed the value of its highest label.• a string (bounded or unbounded) may not be NULL. (Use “” for an empty string

instead).• the length of a bounded string may not exceed the limit specified in IDL.• the length of a bounded sequence may not exceed the limit specified in IDL.If any of these restrictions is violated when validity checking is enabled, theoperation will fail and return a DDS_RETCODE_BAD_PARAMETER. More specificinformation about the context of this error will be written to the error log. Whenvalidity checking is disabled, any of these violations may result in undefinedbehaviour.Be aware that it is not possible for the middleware to determine whether a union iscorrectly initialized, since according to the IDL-C language mapping a union justreturns its current contents in the format of the requested branch without performingany checks. It is therefore the responsibility of the application programmer to makesure that the requested branch actually corresponds to the currently active branch.Not doing so may result in undefined behaviour as well.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the value of a data instance is modified.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - handle is not a valid handle orinstance_data is not a valid sample.

• DDS_RETCODE_ALREADY_DELETED - the SPACE_FooDataWriter has alreadybeen deleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_NOT_ENABLED - the SPACE_FooDataWriter is not enabled.

i

373API Reference

3 DCPS Classes and Operations 3.4 Publication Module

• DDS_RETCODE_PRECONDITION_NOT_MET - the handle has not been registeredwith this SPACE_FooDataWriter.

• DDS_RETCODE_TIMEOUT - either the current action overflowed the availableresources as specified by the combination of the DDS_ReliabilityQosPolicy,DDS_HistoryQosPolicy and DDS_ResourceLimitsQosPolicy, or thecurrent action was waiting for data delivery acknowledgement by synchronousDataReaders. This caused blocking of the SPACE_FooDataWriter_writeoperation, which could not be resolved before max_blocking_time of theDDS_ReliabilityQosPolicy elapsed.

3.4.2.58 SPACE_FooDataWriter_write_w_timestamp

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataWriter_write_w_timestamp (SPACE_FooDataWriter _this, const Foo *instance_data, const DDS_InstanceHandle_t handle, const DDS_Time_t *source_timestamp);

DescriptionThis operation modifies the value of a data instance and provides a value for thesource_timestamp explicitly.

Parametersin SPACE_FooDataWriter _this - the SPACE_FooDataWriter object on

which the operation is operated.in const Foo *instance_data - the data to be written.in const DDS_InstanceHandle_t handle - the handle to the instance as

supplied by SPACE_FooDataWriter_register_instance.in const DDS_Time_t *source_timestamp - the timestamp used.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED , DDS_RETCODE_PRECONDITION_NOT_MET o rDDS_RETCODE_TIMEOUT.

374API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Detailed DescriptionThis operation performs the same functions as SPACE_FooDataWriter_writeexcept that the application provides the value for the source_timestamp that ismade available to connected DDS_DataReader objects. This timestamp isimportant for the interpretation of the DDS_DestinationOrderQosPolicy.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the value of a data instance is modified.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - handle is not a valid handle orinstance_data is not a valid sample.

• DDS_RETCODE_ALREADY_DELETED - the SPACE_FooDataWriter has alreadybeen deleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_NOT_ENABLED - the SPACE_FooDataWriter is not enabled.• DDS_RETCODE_PRECONDITION_NOT_MET - the instance_data does not

correspond to the handle that should have been obtained from thisSPACE_FooDataWriter.

• DDS_RETCODE_TIMEOUT - either the current action overflowed the availableresources as specified by the combination of the DDS_ReliabilityQosPolicy,DDS_HistoryQosPolicy and DDS_ResourceLimitsQosPolicy, or thecurrent action was waiting for data delivery acknowledgement by synchronousDataReaders. This caused blocking of theSPACE_FooDataWriter_register_instance_w_timestamp operation,which could not be resolved before max_blocking_time of theDDS_ReliabilityQosPolicy elapsed.

3.4.2.59 SPACE_FooDataWriter_writedispose

Synopsis#include <Space.h>

DDS_ReturnCode_t SPACE_FooDataWriter_writedispose

(SPACE_FooDataWriter _this, const Foo *instance_data, const DDS_InstanceHandle_t handle);

375API Reference

3 DCPS Classes and Operations 3.4 Publication Module

DescriptionThis operation modifies and disposes a data instance.

Parametersin SPACE_FooDataWriter _this - the SPACE_FooDataWriter object on

which the operation is operated.in const Foo *instance_data - the data to be written and disposed.in const DDS_InstanceHandle_t instance - the handle to the instance as

supplied by SPACE_FooDataWriter_register_instance.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED , DDS_RETCODE_PRECONDITION_NOT_MET o rDDS_RETCODE_TIMEOUT.

Detailed DescriptionThis operation requests the Data Distribution Service to modify the instance andmark it for deletion. Copies of the instance and its corresponding samples, which arestored in every connected DDS_DataReader and, dependent on the QoSPolicysettings, also in the Transient and Persistent stores, will be modified and marked fordeletion by setting their DDS_InstanceStateKind to DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE. When this operation is used, the Data Distribution Service will automatically supplythe value of the source_timestamp that is made available to connectedDDS_DataReader objects. This timestamp is important for the interpretation of theDDS_DestinationOrderQosPolicy.As a side effect, this operation asserts liveliness on the DDS_DataWriter itself andon the containing DDS_DomainParticipant.

Effects on DataReadersActual deletion of the instance administration in a connected DDS_DataReaderwill be postponed until the following conditions have been met:• the instance must be unregistered (either implicitly or explicitly) by all connectedDDS_DataWriters that have previously registered it.

376API Reference

3 DCPS Classes and Operations 3.4 Publication Module

- A DDS_DataWriter can register an instance explicitly by using one of thespecial operations SPACE_FooDataWriter_register_instance orSPACE_FooDataWriter_register_instance_w_timestamp.

- A DDS_DataWriter can register an instance implicitly by using the specialconstant DDS_HANDLE_NIL in any of the other DDS_DataWriter operations.

- A DDS_DataWriter can unregister an instance explicitly by using one of thespecial operations SPACE_FooDataWriter_unregister_instance orSPACE_FooDataWriter_unregister_ instance_w_timestamp.

- A DDS_DataWriter will unregister all its contained instances implicitly whenit is deleted.

- When a DDS_DataReader detects a loss of liveliness in one of its connectedDDS_DataWriters, it will consider all instances registered by thatDDS_DataWriter as being implicitly unregistered.

• and the application must have consumed all samples belonging to the instance,either implicitly or explicitly. - An application can consume samples explicitly by invoking theSPACE_FooDataReader_take operation, or one of its variants.

- The DDS_DataReader can consume disposed samples implicitly when theautopurge_disposed_samples_delay of the DDS_ReaderDataLifecycleQosPolicy has expired.

The DDS_DataReader may also remove instances that haven’t been disposed first:this happens when the autopurge_nowriter_samples_delay of theDDS_ReaderDataLifecycleQosPolicy has expired after the instance isconsidered unregistered by all connected DDS_DataWriters (i.e. when it has aDDS_InstanceStateKind of DDS_NOT_ALIVE_NO_WRITERS). See also Section3.1.3.15, DDS_ReaderDataLifecycleQosPolicy, on page 99.

Effects on Transient/Persistent StoresActual deletion of the instance administration in the connected Transient andPersistent stores will be postponed until the following conditions have been met:• the instance must be unregistered (either implicitly or explicitly) by all connectedDDS_DataWriters that have previously registered it. (See above.)

• and the period of time specified by the service_cleanup_delay attribute inthe DDS_DurabilityServiceQosPolicy on the DDS_Topic must haveelapsed after the instance is considered unregistered by all connectedDDS_DataWriters.

See also Section 3.1.3.4, DDS_DurabilityServiceQosPolicy, on page 76.

377API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Instance HandleThe DDS_HANDLE_NIL handle value can be used for the parameter handle. Thisindicates the identity of the instance is automatically deduced from theinstance_data (by means of the key).If handle is any value other than DDS_HANDLE_NIL, it must correspond to thevalue returned by SPACE_FooDataWriter_register_instance orSPACE_FooDataWriter_register_instance_w_timestamp when theinstance (identified by its key) was registered. Passing such a registered handlehelps the Data Distribution Service to process the sample more efficiently. If there isno correspondence between handle and sample, the result of the operation isunspecified.The sample that is passed as instance_data will actually be delivered to theconnected DDS_DataReaders, but will immediately be marked for deletion.

BlockingIf the DDS_HistoryQosPolicy is set to DDS_KEEP_ALL_HISTORY_QOS, theSPACE_FooDataWriter_writedispose operation on the DDS_DataWritermay block if the modification would cause data to be lost because one of the limits,specified in the DDS_ResourceLimitsQosPolicy, to be exceeded. In case thesynchronous attribute value of the ReliabilityQosPolicy is set to TRUE forcommunicating DataWriters and DataReaders then the DataWriter will waituntil all synchronous DataReaders have acknowledged the data. Under thesec i r c u m s t a n c e s , t h e max_blocking_time a t t r i b u t e o f t h eReliabilityQosPolicy c o n f i g u r e s t h e m a x i m u m t i m e t h eSPACE_FooDataWriter_writedispose operation may block (either waiting forspace to become available or data to be acknowledged). If max_blocking_timeelapses before the DDS_DataWriter is able to store the modification withoutexceeding the limits and all expected acknowledgements are received, theSPACE_FooDataWriter_writedispose operation will fail and returnsDDS_RETCODE_TIMEOUT.

Sample ValidationOpenSplice offers the possibility to check the sample that is passed asinstance_data for validity. Because validity checking might reduce the overallperformance, it is by default disabled. This has been done by enclosing the validitychecking with conditional compiler directives like this:

#ifdef OSPL_BOUNDS_CHECK // check a specific bound.#endif

378API Reference

3 DCPS Classes and Operations 3.4 Publication Module

By defining a macro called OSPL_OSPL_BOUNDS_CHECK, the validity checking willbe included. On most compilers this macro can be defined by passing an additionalcommand line parameter called -DOSPL_BOUNDS_CHECK.Before the sample is accepted by the DataWriter, it is validated against therestrictions imposed by the IDL to C language mapping, where:• an enum may not exceed the value of its highest label• a string (bounded or unbounded) may not be NULL. (Use “” for an empty string

instead)• the length of a bounded string may not exceed the limit specified in IDL• the length of a bounded sequence may not exceed the limit specified in IDLIf any of these restrictions is violated when validity checking is enabled, theoperation will fail and return a DDS_RETCODE_BAD_PARAMETER. More specificinformation about the context of this error will be written to the error log. Whenvalidity checking is disabled, any of these violations may result in undefinedbehaviour.Be aware that it is not possible for the middleware to determine whether a union iscorrectly initialized, since according to the IDL-C language mapping a union justreturns its current contents in the format of the requested branch without performingany checks. It is therefore the responsibility of the application programmer to makesure that the requested branch actually corresponds to the currently active branch.Not doing so may result in undefined behaviour as well.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the Data Distribution Service has modified the instance and

marked it for deletion.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - instance_handle is not a valid handle orinstance_data is not a valid sample.

• DDS_RETCODE_ALREADY_DELETED - the SPACE_FooDataWriter has alreadybeen deleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_NOT_ENABLED - the SPACE_FooDataWriter is not enabled.

i

379API Reference

3 DCPS Classes and Operations 3.4 Publication Module

• DDS_RETCODE_PRECONDITION_NOT_MET - the instance_handle has notbeen registered with this SPACE_FooDataWriter.

• DDS_RETCODE_TIMEOUT - either the current action overflowed the availableresources as specified by the combination of the DDS_ReliabilityQosPolicy,DDS_HistoryQosPolicy and DDS_ResourceLimitsQosPolicy, or thecurrent action was waiting for data delivery acknowledgement by synchronousDataReaders. This caused blocking of theSPACE_FooDataWriter_writedispose operation, which could not beresolved before max_blocking_time of the DDS_ReliabilityQosPolicyelapsed.

3.4.2.60 SPACE_FooDataWriter_writedispose_w_timestamp

Synopsis#include <Space.h>

DDS_ReturnCode_t SPACE_FooDataWriter_writedispose_w_timestamp

(SPACE_FooDataWriter _this, const Foo *instance_data, const DDS_InstanceHandle_t handle, const DDS_Time_t *source_timestamp);

DescriptionThis operation requests the Data Distribution Service to modify the instance andmark it for deletion, and provides a value for the source_timestamp explicitly.

Parametersin SPACE_FooDataWriter _this - the SPACE_FooDataWriter object on

which the operation is operated.in const Foo *instance_data - the data to be written and disposed.in const DDS_InstanceHandle_t handle - the handle to the instance as

supplied by SPACE_FooDataWriter_register_instance.in const DDS_Time_t *source_timestamp - the timestamp used.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED , DDS_RETCODE_PRECONDITION_NOT_MET o rDDS_RETCODE_TIMEOUT.

380API Reference

3 DCPS Classes and Operations 3.4 Publication Module

Detailed DescriptionT h i s o p e r a t i o n p e r f o r m s t h e s a m e f u n c t i o n s a sSPACE_FooDataWriter_writedispose except that the application provides thevalue for the source_timestamp that is made available to connectedDDS_DataReader objects. This timestamp is important for the interpretation of theDDS_DestinationOrderQosPolicy.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the Data Distribution Service has modified the instance and

marked it for deletion.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - handle is not a valid handle orinstance_data is not a valid sample.

• DDS_RETCODE_ALREADY_DELETED - the SPACE_FooDataWriter has alreadybeen deleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_NOT_ENABLED - the SPACE_FooDataWriter is not enabled.• DDS_RETCODE_PRECONDITION_NOT_MET - the handle has not been registered

with this SPACE_FooDataWriter.• DDS_RETCODE_TIMEOUT - either the current action overflowed the available

resources as specified by the combination of the DDS_ReliabilityQosPolicy,DDS_HistoryQosPolicy and DDS_ResourceLimitsQosPolicy, or thecurrent action was waiting for data delivery acknowledgement by synchronousDataReaders. This caused blocking of theSPACE_FooDataWriter_writedispose_w_timestamp operation, whichcould not be resolved before max_blocking_time of theDDS_ReliabilityQosPolicy elapsed.

3.4.3 DDS_PublisherListener interfaceSince a DDS_Publisher is a DDS_Entity, it has the ability to have a Listenerassociated with it. In this case, the associated Listener should be of typeDDS_PublisherListener. This interface must be implemented by theapplication. A user-defined class must be provided by the application which must

381API Reference

3 DCPS Classes and Operations 3.4 Publication Module

extend from the DDS_PublisherListener class. All DDS_PublisherListeneroperations must be implemented in the user-defined class, it is up to the applicationwhether an operation is empty or contains some functionality.

All operations for this interface must be implemented in the user-defined class, it isup to the application whether an operation is empty or contains some functionality.

The DDS_PublisherListener provides a generic mechanism (actually a callbackfunction) for the Data Distribution Service to notify the application of relevantasynchronous status change events, such as a missed deadline, violation of aQosPolicy setting, etc. The DDS_PublisherListener is related to changes incommunication status.The interface description of this class is as follows:

/* * interface DDS_PublisherListener *//* * inherited from DDS_DataWriterListener *//* void * DDS_PublisherListener_on_offered_deadline_missed * (void *listener_data, * DDS_DataWriter writer, * const DDS_OfferedDeadlineMissedStatus *status);

*//* void * DDS_PublisherListener_on_offered_incompatible_qos * (void *listener_data, * DDS_DataWriter writer, * const DDS_OfferedIncompatibleQosStatus *status); */

/* void * DDS_PublisherListener_on_liveliness_lost * (void *listener_data, * DDS_DataWriter writer, * const DDS_LivelinessLostStatus *status); */

/* void * DDS_PublisherListener_on_publication_matched * (void *listener_data, * DDS_DataWriter writer, * const DDS_PublicationMatchedStatus *status); *//* * implemented API operations

382API Reference

3 DCPS Classes and Operations 3.4 Publication Module

*/struct DDS_PublisherListener * DDS_PublisherListener__alloc (void);

The next paragraphs list all DDS_PublisherListener operations. Since theseoperations are all inherited, they are listed but not fully described because they arenot implemented in this class. The full description of these operations is given in theclasses from which they are inherited.

3.4.3.1 DDS_PublisherListener__alloc

Synopsis#include <dds_dcps.h>struct DDS_PublisherListener * DDS_PublisherListener__alloc (void);

DescriptionThis operation creates a new DDS_PublisherListener.

Parameters<none>

Return Valuestruct DDS_PublisherListener * - the handle to the newly-created

DDS_PublisherListener. In case of an error, a DDS_OBJECT_NIL pointer isreturned.

Detailed DescriptionT h i s o p e r a t i o n c r e a t e s a n e w DDS_PublisherListener. Th eDDS_PublisherListener must be created using this operation. In other words,t h e a p p l i c a t i o n i s n o t a l l o w e d t o d e c l a r e a n o b j e c t o f t y p eDDS_PublisherListener. When the application wants to release theDDS_PublisherListener it must be released using DDS_free.I n c a s e t h e r e a r e i n s u ff i c i e n t r e s o u r c e s a v a i l a b l e t o a l l o c a t e t h eDDS_PublisherListener, a DDS_OBJECT_NIL pointer is returned instead.

3.4.3.2 DDS_PublisherListener_on_liveliness_lost (inherited, abstract)This operation is inherited and therefore not described here. See the classDDS_DataWriterListener for further explanation.

Synopsis#include <dds_dcps.h>

383API Reference

3 DCPS Classes and Operations 3.4 Publication Module

void DDS_PublisherListener_on_liveliness_lost (void *listener_data, DDS_DataWriter writer, const DDS_LivelinessLostStatus *status);

3.4.3.3 DDS_PublisherListener_on_offered_deadline_missed (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_DataWriterListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_PublisherListener_on_offered_deadline_missed (void *listener_data, DDS_DataWriter writer, const DDS_OfferedDeadlineMissedStatus *status);

3.4.3.4 DDS_PublisherListener_on_offered_incompatible_qos (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_DataWriterListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_PublisherListener_on_offered_incompatible_qos (void *listener_data, DDS_DataWriter writer, const DDS_OfferedIncompatibleQosStatus *status);

3.4.3.5 DDS_PublisherListener_on_publication_matched (inherited, abstract)This operation is inherited and therefore not described here. See the classDDS_DataWriterListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_PublisherListener_on_publication_matched (void *listener_data, DDS_DataWriter writer, const DDS_PublicationMatchedStatus *status);

384API Reference

3 DCPS Classes and Operations 3.4 Publication Module

3.4.4 DDS_DataWriterListener interfaceSince a DDS_DataWriter is a DDS_Entity, it has the ability to have a Listenerassociated with it. In this case, the associated Listener should be of typeDDS_DataWriterListener. This interface must be implemented by theapplication. A user-defined class must be provided by the application which muste x t e n d f r o m t h e DDS_DataWriterListener c l a s s . A l lDDS_DataWriterListener operations must be implemented in the user-definedclass, it is up to the application whether an operation is empty or contains somefunctionality.

NOTE: All operations for this interface must be implemented in the user-definedclass; it is up to the application whether an operation is empty or contains somefunctionality.

The DDS_DataWriterListener provides a generic mechanism (actually acallback function) for the Data Distribution Service to notify the application ofrelevant asynchronous status change events, such as a missed deadline, violation ofa QosPolicy setting, etc. The DDS_DataWriterListener is related to changesin communication status.The interface description of this class is as follows:

/* * interface DDS_DataWriterListener *//* * abstract external operations */

void DDS_DataWriterListener_on_offered_deadline_missed

(void *listener_data, DDS_DataWriter writer,

const DDS_OfferedDeadlineMissedStatus *status);

void DDS_DataWriterListener_on_offered_incompatible_qos

(void *listener_data, DDS_DataWriter writer,

const DDS_OfferedIncompatibleQosStatus *status);

void DDS_DataWriterListener_on_liveliness_lost

(void *listener_data, DDS_DataWriter writer,

const DDS_LivelinessLostStatus *status);

void

385API Reference

3 DCPS Classes and Operations 3.4 Publication Module

DDS_DataWriterListener_on_publication_matched (void *listener_data,

DDS_DataWriter writer, const DDS_PublicationMatchedStatus *status);

/* * implemented API operations */

struct DDS_DataWriterListener * DDS_DataWriterListener__alloc (void);

The next paragraphs describe the usage of all DDS_DataWriterListeneroperations. These abstract operations are fully described because they must beimplemented by the application.

3.4.4.1 DDS_DataWriterListener__alloc

Synopsis#include <dds_dcps.h>struct DDS_DataWriterListener * DDS_DataWriterListener__alloc (void);

DescriptionThis operation creates a new DDS_DataWriterListener.

Parameters<none>

Return Valuestruct DDS_DataWriterListener * - the handle to the newly-created

DDS_DataWriterListener. In case of an error, a DDS_OBJECT_NIL pointeris returned.

Detailed DescriptionThi s ope ra t i on c r ea t e s a new DDS_DataWriterListener. T h eDDS_DataWriterListener must be created using this operation. In other words,t h e a p p l i c a t i o n i s n o t a l l o w e d t o d e c l a r e a n o b j e c t o f t y p eDDS_DataWriterListener. When the application wants to release theDDS_DataWriterListener it must be released using DDS_free.I n c a s e t h e r e a r e i n s u ff i c i e n t r e s o u r c e s a v a i l a b l e t o a l l o c a t e t h eDDS_DataWriterListener, a DDS_OBJECT_NIL pointer is returned instead.

386API Reference

3 DCPS Classes and Operations 3.4 Publication Module

3.4.4.2 DDS_DataWriterListener_on_liveliness_lost (abstract)

Synopsis#include <dds_dcps.h>void DDS_DataWriterListener_on_liveliness_lost (void *listener_data, DDS_DataWriter writer, const DDS_LivelinessLostStatus *status);

DescriptionThis operation must be implemented by the application and is called by the DataDistribution Service when the DDS_LivelinessLostStatus changes.

Parametersinout void *listener_data - a pointer to a user-defined object which may be

used for identification of the Listener.in DDS_DataWriter writer - contain a pointer to the DDS_DataWriter on

which the DDS_LivelinessLostStatus has changed (this is an input to theapplication).

in const DDS_LivelinessLostStatus *status - conta in theDDS_LivelinessLostStatus struct (this is an input to the application).

Return Value<none>

Detailed DescriptionThis operation is the external operation (interface, which must be implemented bythe application) that is called by the Data Distribution Service when theDDS_LivelinessLostStatus changes. The implementation may be left emptywhen this functionality is not needed. This operation will only be called when therelevant DDS_DataWriterListener is installed and enabled for the liveliness loststatus. The liveliness lost status will change when the liveliness that theDDS_DataWriter has committed through its DDS_LivelinessQosPolicy wasnot respected. In other words, the DDS_DataWriter failed to actively signal itsliveliness within the offered liveliness period. As a result, the DDS_DataReaderobjects will consider the DDS_DataWriter as no longer “alive”.The Data Distribution Service will call the DDS_DataWriterListener operationwith a parameter writer, which will contain a pointer to the DDS_DataWriter onwhich the conflict occurred and a parameter status, which will contain theDDS_LivelinessLostStatus struct.

387API Reference

3 DCPS Classes and Operations 3.4 Publication Module

3.4.4.3 DDS_DataWriterListener_on_offered_deadline_missed (abstract)

Synopsis#include <dds_dcps.h>void DDS_DataWriterListener_on_offered_deadline_missed (void *listener_data, DDS_DataWriter writer, const DDS_OfferedDeadlineMissedStatus *status);

DescriptionThis operation must be implemented by the application and is called by the DataDistribution Service when the DDS_OfferedDeadlineMissedStatus changes.

Parametersinout void *listener_data - a pointer to a user-defined object which may be

used for identification of the Listener.in DDS_DataWriter writer - contains a pointer to the DDS_DataWriter on

which the DDS_OfferedDeadlineMissedStatus has changed (this is aninput to the application).

in const DDS_OfferedDeadlineMissedStatus *status - contains theDDS_OfferedDeadlineMissedStatus struct (this is an input to theapplication).

Return Value<none>

Detailed DescriptionThis operation is the external operation (interface, which must be implemented bythe application) that is called by the Data Distribution Service when theDDS_OfferedDeadlineMissedStatus changes. The implementation may be leftempty when this functionality is not needed. This operation will only be called whenthe relevant DDS_DataWriterListener is installed and enabled for the offereddeadline missed status. The offered deadline missed status will change when thed e a d l i n e t h a t t h e DDS_DataWriter h a s c o m m i t t e d t h r o u g h i t sDDS_DeadlineQosPolicy was not respected for a specific instance.The Data Distribution Service will call the DDS_DataWriterListener operationwith a parameter writer, which will contain a pointer to the DDS_DataWriter onwhich the conflict occurred and a parameter status, which will contain theDDS_OfferedDeadlineMissedStatus struct.

388API Reference

3 DCPS Classes and Operations 3.4 Publication Module

3.4.4.4 DDS_DataWriterListener_on_offered_incompatible_qos (abstract)

Synopsis#include <dds_dcps.h>void DDS_DataWriterListener_on_offered_incompatible_qos (void *listener_data, DDS_DataWriter writer, const DDS_OfferedIncompatibleQosStatus *status);

DescriptionThis operation must be implemented by the application and is called by the DataDistribution Service when the DDS_OFFERED_INCOMPATIBLE_QOS_STATUSchanges.

Parametersinout void *listener_data - a pointer to a user-defined object which may be

used for identification of the Listener.in DDS_DataWriter writer - contain a pointer to the DDS_DataWriter on

which the DDS_OFFERED_INCOMPATIBLE_QOS_STATUS has changed (this isan input to the application).

in const DDS_OfferedIncompatibleQosStatus *status - contain theDDS_OfferedIncompatibleQosStatus struct (this is an input to theapplication).

Return Value<none>

Detailed DescriptionThis operation is the external operation (interface, which must be implemented bythe application) that is called by the Data Distribution Service when theDDS_OFFERED_INCOMPATIBLE_QOS_STATUS changes. The implementation maybe left empty when this functionality is not needed. This operation will only becalled when the relevant DDS_DataWriterListener is installed and enabled forthe DDS_OFFERED_INCOMPATIBLE_QOS_STATUS. The incompatible Qos statuswill change when a DDS_DataReader object has been discovered by theDDS_DataWriter w i t h t h e s a m e DDS_Topic and a r eques t e dDDS_DataReaderQos that was incompatible with the one offered by theDDS_DataWriter.

389API Reference

3 DCPS Classes and Operations 3.4 Publication Module

The Data Distribution Service will call the DDS_DataWriterListener operationwith a parameter writer, which will contain a pointer to the DDS_DataWriter onwhich the conflict occurred and a parameter status, which will contain theDDS_OfferedIncompatibleQosStatus struct.

3.4.4.5 DDS_DataWriterListener_on_publication_matched (abstract)

Synopsis#include <dds_dcps.h>void DDS_DataWriterListener_on_publication_matched (DDS_DataWritervoid *listener_data, DDS_DataWriter writer, const DDS_PublicationMatchedStatus *status);

DescriptionThis operation must be implemented by the application and is called by the DataDistribution Service when a new match has been discovered for the currentpublication, or when an existing match has ceased to exist.

Parametersinout void *listener_data - a pointer to a user-defined object which may be

used for identification of the Listener.in DDS_DataWriter writer - contains a pointer to the DDS_DataWriter for

which a match has been discovered (this is an input to the application providedby the Data Distribution Service).

in const DDS_PublicationMatchedStatus *status - contains theDDS_PublicationMatchedStatus struct (this is an input to the applicationprovided by the Data Distribution Service).

Return Value<none>

Detailed DescriptionThis operation must be implemented by the application and is called by the DataDistribution Service when a new match has been discovered for the currentpublication, or when an existing match has ceased to exist. Usually this means that anew DataReader that matches the Topic and that has compatible Qos as the currentDDS_DataWriter has either been discovered, or that a previously discoveredDataReader has ceased to be matched to the current DDS_DataWriter. ADataReader may cease to match when it gets deleted, when it changes its Qos to avalue that is incompatible with the current DDS_DataWriter or when either the

390API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

DDS_DataWriter or the DataReader has chosen to put its matching counterpart onits ignore-list using the DDS_DomainParticipant_ignore_subcription orDDS_DomainParticipant_ignore_publication operations. The implementation of this Listener operation may be left empty when thisfunctionali ty is not needed: i t wil l only be cal led when the relevantDDS_DataWriterListener i s i n s t a l l e d a n d e n a b le d f o r t h eDDS_PUBLICATION_MATCHED_STATUS.The Data Distribution Service will provide a pointer to the DDS_DataWriter in theparameter writer and the DDS_PublicationMatchedStatus struct in theparameter status for use by the application.

3.5 Subscription Module

Figure 19: The DCPS Subscription Module’s Class Model

QueryCondition

get_query_parameters()get_query_expression()set_query_parameters()

DomainParticipant(from Domain Module)

SampleInfosample_stateview_stateinstance_statesource_timestampinstance_handledisposed_generation_countno_writers_generation_countsample_rankgeneration_rankabsolute_generation_rank

WaitSet(from Infrastructure Module)

Topic(from Topic-Definition Module)

SubscriberListener

on_data_on_readers()

<<Interface>>

TopicDescription(from Topic-Definition Module)

**

<<implicit>>

DataReaderListener

on_data_available()on_liveliness_changed()on_requested_deadline_missed()on_requested_incompatible_qos()on_sample_lost()on_sample_rejected()on_subscription_match()

<<Interface>>

DataSample

11

ReadCondition

get_datareader()get_instance_state_mask()get_sample_state_mask()get_view_state_mask()

*

*

*

*<<implicit>>

StatusCondition(from Infrastructure Module)

** **

QosPolicyname : string

**

Subscriber

begin_access()copy_from_topic_qos()create_datareader()delete_contained_entities()delete_datareader()end_access()get_datareaders()get_default_datareader_qos()get_listener()get_participant()get_qos()lookup_datareader()notify_datareaders()set_default_datareader_qos()set_listener()set_qos()

0..10..1

<<implicit>>

1

0..1

1

0..1

<<implicit>>

**

qos<<implicit>>

**

default_datareader_qos

DataReader

create_querycondition()create_readcondition()delete_contained_entities()delete_readcondition()<<abstract>> get_key_value()get_listener()get_liveliness_changed_status()get_matched_publication_data()get_matched_publications()get_qos()get_requested_deadline_missed_status()get_requested_incompatible_qos_status()get_sample_lost_status()get_sample_rejected_status()get_subscriber()get_subscription_match_status()get_topicdescription()<<abstract>> lookup_instance()<<abstract>> read()<<abstract>> read_instance()<<abstract>> read_next_instance()<<abstract>> read_next_instance_w_condition()<<abstract>> read_next_sample()<<abstract>> read_w_condition()<<abstract>> return_loan()set_listener()set_qos()<<abstract>> take()<<abstract>> take_instance()<<abstract>> take_next_instance()<<abstract>> take_next_instance_w_condition()<<abstract>> take_next_sample()<<abstract>> take_w_condition()

*1

*1

0..10..1

**

*

1

*

1

0..1

<<implicit>>

**

<<implicit>>

1

*

1

*

<<create>>

<<create>>

<<create>>

<<create>>

391API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

This module contains the following classes:• DDS_Subscriber • Subscription type specific classes• DDS_DataSample • DDS_SampleInfo (struct)• DDS_SubscriberListener (interface)• DDS_DataReaderListener (interface)• DDS_ReadCondition • DDS_QueryCondition

“Subscription type specific classes” contains the generic class and the generateddata type specific classes. For each data type, a data type specific class<NameSpace>_<type>DataReader is generated (based on IDL) by calling thepre-processor.For instance, for the fictional data type Foo (this also applies to other types), definedin the module SPACE; “Subscription type specific classes” contains the followingclasses:• DDS_DataReader (abstract)

• SPACE_FooDataReader

• DDS_DataReaderView (abstract)

• SPACE_FooDataReaderView

A DDS_Subscriber is an object responsible for receiving published data andmaking it available (according to the DDS_SubscriberQos) to the application. Itmay receive and dispatch DDS_Topic with data of different specified data types. Toaccess the received data, the application must use a typed DDS_DataReaderattached to the DDS_Subscriber. Thus, a subscription is defined by the associationof a DDS_DataReader with a DDS_Subscriber. This association expresses theintent of the application to subscribe to the data described by the DDS_DataReaderin the context provided by the DDS_Subscriber.

3.5.1 Class DDS_SubscriberA DDS_Subscriber is the object responsible for the actual reception of the dataresulting from its subscriptions.A DDS_Subscriber acts on behalf of one or more DDS_DataReader objects thatare related to it. When it receives data (from the other parts of the system), iti n d i c a t e s t o t h e a p p l i c a t i o n t h a t d a t a i s a v a i l a b l e t h r o u g h i t sDDS_DataReaderListener and by enabling related DDS_Conditions. The

392API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

application can access the list of concerned DDS_DataReader objects through theoperation DDS_Subscriber_get_datareaders and then access the dataavailable through operations on the DDS_DataReader.The interface description of this class is as follows:

/* * interface DDS_Subscriber *//* * inherited from class DDS_Entity *//* DDS_StatusCondition * DDS_Subscriber_get_statuscondition * (DDS_Subscriber _this) *//* DDS_StatusMask * DDS_Subscriber_get_status_changes * (DDS_Subscriber _this); *//* DDS_ReturnCode_t * DDS_Subscriber_enable * (DDS_Subscriber _this); *//* * implemented API operations */

DDS_DataReader DDS_Subscriber_create_datareader (DDS_Subscriber _this, const DDS_TopicDescription a_topic,

const DDS_DataReaderQos *qos, const struct DDS_DataReaderListener *a_listener, const DDS_StatusMask mask);

DDS_ReturnCode_t DDS_Subscriber_delete_datareader (DDS_Subscriber _this, const DDS_DataReader a_datareader);

DDS_ReturnCode_t DDS_Subscriber_delete_contained_entities (DDS_Subscriber _this);

DDS_DataReader DDS_Subscriber_lookup_datareader (DDS_Subscriber _this, const DDS_char *topic_name);

DDS_ReturnCode_t

393API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

DDS_Subscriber_get_datareaders (DDS_Subscriber _this, DDS_DataReaderSeq *readers,

const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

DDS_ReturnCode_t DDS_Subscriber_notify_datareaders (DDS_Subscriber _this);

DDS_ReturnCode_t DDS_Subscriber_set_qos (DDS_Subscriber _this, const DDS_SubscriberQos *qos);

DDS_ReturnCode_t DDS_Subscriber_get_qos (DDS_Subscriber _this, DDS_SubscriberQos *qos);DDS_ReturnCode_t DDS_Subscriber_set_listener (DDS_Subscriber _this, const struct DDS_SubscriberListener *a_listener, const DDS_StatusMask mask);

struct DDS_SubscriberListener DDS_Subscriber_get_listener (DDS_Subscriber _this);

DDS_ReturnCode_t DDS_Subscriber_begin_access (DDS_Subscriber _this);

DDS_ReturnCode_t DDS_Subscriber_end_access (DDS_Subscriber _this);

DDS_DomainParticipant DDS_Subscriber_get_participant (DDS_Subscriber _this);

DDS_ReturnCode_t DDS_Subscriber_set_default_datareader_qos (DDS_Subscriber _this, const DDS_DataReaderQos *qos);

DDS_ReturnCode_t DDS_Subscriber_get_default_datareader_qos (DDS_Subscriber _this,

394API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

DDS_DataReaderQos *qos);

DDS_ReturnCode_t DDS_Subscriber_copy_from_topic_qos (DDS_Subscriber _this, DDS_DataReaderQos *a_datareader_qos,

const DDS_TopicQos *a_topic_qos);

The next paragraphs describe the usage of all DDS_Subscriber operations. Theinherited operations are listed but not fully described because they are notimplemented in this class. The full description of these operations is given in theclasses from which they are inherited.

3.5.1.1 DDS_Subscriber_begin_access

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Subscriber_begin_access (DDS_Subscriber _this);

DescriptionThis operation indicates that the application will begin accessing a coherent and/orordered set of modifications that spans multiple DataReaders attached to thisS u b s c r i b e r. T h e a c c e s s w i l l b e c o m p l e t e d b y a m a t c h i n g c a l l t oDDS_Subscriber_end_access.

Parametersin DDS_Subscriber _this - the DDS_Subscriber object on which the

operation is operated.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER or DDS_RETCODE_ALREADY_DELETED.

Detailed DescriptionThis operation indicates that the application is about to access a set of coherentand/or ordered samples in any of the DataReader objects attached to the Subscriber.The operation will effectively lock all of the Subscriber’s DataReader objects forany incoming modifications, so that the state of their history remains consistent for

395API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

the duration of the access. Note that a coherent subscriber should first be enabled,otherwise this operation will return DDS_RETCODE_ERROR. See Section 3.5.1.6,DDS_Subscriber_enable (inherited), for additional information. The application is required to use this operation only if the PresentationQosPolicy ofthe Subscriber to which the DataReader belongs has the access_scope set to‘GROUP ’ . I n t h e a f o r e m e n t i o n e d c a s e , t h e o p e r a t i o nDDS_Subscriber_begin_access must be called prior to calling any of thesample-accessing operations, namely: get_datareaders on the Subscriber andread , take , and all their variants on any DataReader. Otherwise thes a m p l e - a c c e s s i n g o p e r a t i o n s w i l l r e t u r n t h e e r r o rDDS_RETCODE_PRECONDITION_NOT_MET. Once the application has finishedaccessing the data samples it must call DDS_Subscriber_end_access.It is not required for the application to call begin_access/end_access if thePresentationQosPolicy has the access_scope set to something other than‘GROUP’. Calling begin_access/end_access in this case is not considered anerror and has no effect.The calls to begin_access/end_access may be nested. In that case, theapplication must call end_access as many times as it called begin_access.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - access to coherent/ordered data has successfully started.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter passed to the operation is NULL,

or is not pointing to any valid object.• DDS_RETCODE_ALREADY_DELETED - the DDS_Subscriber has already been

deleted.

3.5.1.2 DDS_Subscriber_copy_from_topic_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Subscriber_copy_from_topic_qos (DDS_Subscriber _this, DDS_DataReaderQos *a_datareader_qos, const DDS_TopicQos *a_topic_qos);

396API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

DescriptionThis operation will copy the policies in a_topic_qos to the corresponding policiesin a_datareader_qos.

Parametersin DDS_Subscriber _this - the DDS_Subscriber object on which the

operation is operated.inout DDS_DataReaderQos *a_datareader_qos - the destination

DDS_DataReaderQos struct to which the QosPolicy settings will be copied.in const DDS_TopicQos *a_topic_qos - the source DDS_TopicQos, which

will be copied.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation will copy the QosPolicy settings in a_topic_qos to thecorresponding QosPolicy settings in a_datareader_qos (replacing the valuesin a_datareader_qos, if present).This is a “convenience” operation, useful in combination with the operationsDDS_Publisher_get_default_datawriter_qos and DDS_Topic_get_qos.The operation DDS_Subscriber_copy_from_topic_qos can be used to mergethe DDS_DataReader default QosPolicy settings with the corresponding ones onthe DDS_Topic. The resulting DDS_DataReaderQos can then be used to create anew DDS_DataReader, or set its DDS_DataReaderQos.This operation does not check the resulting a_datareader_qos for selfconsistency. This is because the “merged” a_datareader_qos may not be thefinal one, as the application can still modify some QosPolicy settings prior toapplying the DDS_DataReaderQos to the DDS_DataReader.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the QosPolicy settings have successfully been copied from

the DDS_TopicQos to the DDS_DataReaderQos.• DDS_RETCODE_ERROR - an internal error has occurred.

397API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on aninappropriate object.

• DDS_RETCODE_ALREADY_DELETED - the DDS_Subscriber has already beendeleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

3.5.1.3 DDS_Subscriber_create_datareaderSynopsis#include <dds_dcps.h>DDS_DataReader DDS_Subscriber_create_datareader (DDS_Subscriber _this, const DDS_TopicDescription a_topic, const DDS_DataReaderQos *qos, const struct DDS_DataReaderListener *a_listener, const DDS_StatusMask mask);

DescriptionThis operation creates a DDS_DataReader with the desired QosPolicy settings,for the desired DDS_TopicDescription and attaches the optionally specifiedDDS_DataWriterListener to it.

Parametersin DDS_Subscriber _this - the DDS_Subscriber object on which the

operation is operated.in const DDS_TopicDescription a_topic - a po in te r to the

DDS_TopicDescription for which the DDS_DataReader is created. Thismay be a DDS_Topic, DDS_MultiTopic or DDS_ContentFilteredTopic.

in const DDS_DataReaderQos *qos - the struct with the QosPolicy settingsfor the new DDS_DataReader, when these QosPolicy settings are not selfconsistent, no DDS_DataReader is created.

in const struct DDS_DataReaderListener *a_listener - a pointer tothe DDS_DataReaderListener instance which will be attached to the newDDS_DataReader. It is permitted to use DDS_OBJECT_NIL as the value of thelistener: this behaves as a DDS_DataWriterListener whose operationsperform no action.

in const DDS_StatusMask mask - a bit-mask in which each bit enables theinvocation of the DDS_DataReaderListener for a certain status.

398API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Return ValueDDS_DataReader - Return value i s a poin ter to the newly-crea ted

DDS_DataReader. In case of an error, the DDS_OBJECT_NIL pointer isreturned.

Detailed DescriptionThis operation creates a DDS_DataReader with the desired QosPolicy settings,for the desired DDS_TopicDescription and attaches the optionally specifiedDDS_DataReaderListener to it. The DDS_TopicDescription may be aDDS_Topic, DDS_MultiTopic or DDS_ContentFilteredTopic. The returnedDDS_DataReader is attached (and belongs) to the DDS_Subscriber. To deletethe DDS_DataReader the operation DDS_Subscriber_delete_datareader orDDS_Subscriber_delete_contained_entities must be used. If no readrights are defined for the specific topic then the creation of the DataReader willfail.

Application Data TypeThe DDS_DataReader returned by this operation is an object of a derived class,specific to the data type associated with the DDS_TopicDescription. For eacha p p l i c a t i o n - d e f i n e d d a t a t y p e <type> t h e r e i s a c l a s s<NameSpace>_<type>DataReader generated by calling the pre-processor. Thisdata type specific class extends DDS_DataReader and contains the operations toread data of data type <type>.Beca use t he DDS_DataReader m a y r e a d a DDS_Topic ,DDS_ContentFilteredTopic or DDS_MultiTopic, the DDS_DataReader isassociated with the DDS_TopicDescription. The DDS_DataWriter can onlywrite a DDS_Topic, not a DDS_ContentFilteredTopic or DDS_MultiTopic,because these two are constructed at the DDS_Subscriber side.

QosPolicyThe common application pattern to construct the QosPolicy settings for theDDS_DataReader is to:• Retrieve the QosPolicy settings on the associated DDS_TopicDescription

by means of the DDS_Topic_get_qos operation on theDDS_TopicDescription

• Retrieve the default DDS_DataReaderQos by means of theDDS_Subscriber_get_default_datareader_qos operation on theDDS_Subscriber

• Combine those two QosPolicy settings and selectively modify policies asdesired (DDS_Subscriber_copy_from_topic_qos)

399API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

• Use the resulting QosPolicy settings to construct the DDS_DataReader.• In case the specified QosPolicy settings are not self consistent, noDDS_DataReader is created and the DDS_OBJECT_NIL pointer is returned.

Default QoSThe constant DDS_DATAREADER_QOS_DEFAULT can be used as parameter qos tocreate a DDS_DataReader with the default DDS_DataReaderQos as set in theDDS_Subscriber. The effect of using DDS_DATAREADER_QOS_DEFAULT is thes a m e a s c a l l i n g t h e o p e r a t i o nDDS_Subscriber_get_default_datareader_qos and using the resultingDDS_DataReaderQos to create the DDS_DataReader.The special DDS_DATAREADER_QOS_USE_TOPIC_QOS can be used to create aDDS_DataReader with a combination of the default DDS_DataReaderQos andthe DDS_TopicQos . T h e e f f e c t o f u s i n gDDS_DATAREADER_QOS_USE_TOPIC_QOS is the same as calling the operationDDS_Subscriber_get_default_datareader_qos and retrieving theDDS_TopicQos (by means of the operation DDS_Topic_get_qos) and thenco mbin ing t he se two QosPolicy s e t t i n g s u s in g t h e o p e r a t i o nDDS_Subscriber_copy_from_topic_qos, whereby any common policy that isset on the DDS_TopicQos “overrides” the corresponding policy on the defaultDDS_DataReaderQos. The resulting DDS_DataReaderQos is then applied tocreate the DDS_DataReader.

Communication StatusFor each communication status, the StatusChangedFlag flag is initially set toFALSE. It becomes TRUE whenever that communication status changes. For eachco m m un ica t i on s t a t u s a c t i va t ed i n t he mask , t h e a s soc i a t e dDDS_DataReaderListener operation is invoked and the communication status isreset to FALSE, as the listener implicitly accesses the status which is passed as aparameter to that operation. The fact that the status is reset prior to calling thelistener means that if the application calls the get_<status_name>_status frominside the listener it will see the status already reset.The following statuses are applicable to the DDS_DataReaderListener:

DDS_REQUESTED_DEADLINE_MISSED_STATUSDDS_REQUESTED_INCOMPATIBLE_QOS_STATUSDDS_SAMPLE_LOST_STATUSDDS_SAMPLE_REJECTED_STATUSDDS_DATA_AVAILABLE_STATUSDDS_LIVELINESS_CHANGED_STATUSDDS_SUBSCRIPTION_MATCHED_STATUS.

400API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Be aware that the DDS_SUBSCRIPTION_MATCHED_STATUS is not applicable whenthe infrastructure does not have the information available to determine connectivity.This is the case when OpenSplice is configured not to maintain discoveryinformation in the Networking Service. (See also the description of theNetworkService/Discovery[@enabled] attribute in section 4.4.1.6.1on page 244 of the Deployment Guide.) In this case the operation will returnDDS_OBJECT_NIL.Status bits are declared as a constant and can be used by the application in an ORoperation to create a tailored mask. The special constant DDS_STATUS_MASK_NONEcan be used to indicate that the created entity should not respond to any of itsavailable statuses. The DDS will therefore attempt to propagate these statuses to itsfactory. The special constant STATUS_MASK_ANY_V1_2 can be used to select allapplicable statuses specified in the “Data Distribution Service for Real-timeSystems Version 1.2” specification.

Status PropagationIn case a communica t ion s ta tus i s not ac t iva ted in the mask o f theDDS_DataReaderListener, the DDS_SubscriberListener of the containingDDS_Subscriber is invoked (if attached and activated for the status that occurred).T h i s a l l o w s t h e a p p l i c a t i o n to s e t a d e f au l t be hav i ou r i n t h eDDS_SubscriberListener of the containing DDS_Subscriber and aDDS_DataReader specific behaviour when needed. In case the communicationstatus is not activated in the mask of the DDS_SubscriberListener as well, thec o m m u n i c a t i o n s t a t u s w i l l b e p r o p a g a t e d t o t h eDDS_DomainParticipantListener o f t h e c o n t a i n i n gDDS_DomainParticipant. In case the DDS_DomainParticipantListener isalso not attached or the communication status is not activated in its mask, theapplication is not notified of the change.

3.5.1.4 DDS_Subscriber_delete_contained_entities

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Subscriber_delete_contained_entities (DDS_Subscriber _this);

DescriptionThis operation deletes all the DDS_DataReader objects that were created by meanso f t he DDS_Subscriber_create_datareader ope ra t i on on t heDDS_Subscriber.

401API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Parametersin DDS_Subscriber _this - the DDS_Subscriber object on which the

operation is operated.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_ALREADY_DELETED , DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionThis operation deletes all the DDS_DataReader objects that were created by meanso f t he DDS_Subscriber_create_datareader ope ra t i on on t heDDS_Subscriber. In other words, it deletes all contained DDS_DataReaderobjects. Prior to deleting each DDS_DataReader, this operation recursively callsthe corresponding DDS_DataReader_delete_contained_entities operationon each DDS_DataReader. In other words, all DDS_DataReader objects in theDDS_Subscriber are deleted, including the DDS_QueryCondition andDDS_ReadCondition objects contained by the DDS_DataReader.

NOTE: The operation will return DDS_PRECONDITION_NOT_MET if the any of thecontained entities is in a state where it cannot be deleted. This will occur, forexample, if a contained DDS_DataReader cannot be deleted because theapplication has called a read or take operation and has not called thecorresponding return_loan operation to return the loaned samples. In such cases,the operation does not roll back any entity deletions performed prior to the detectionof the problem.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the contained DDS_Entity objects are deleted and the

application may delete the DDS_Subscriber.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_Subscriber has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

402API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

• DDS_RETCODE_PRECONDITION_NOT_MET - one or more of the contained entitiesare in a state where they cannot be deleted.

3.5.1.5 DDS_Subscriber_delete_datareader

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Subscriber_delete_datareader (DDS_Subscriber _this, const DDS_DataReader a_datareader);

DescriptionThis operation deletes a DDS_DataReader that belongs to the DDS_Subscriber.

Parametersin DDS_Subscriber _this - the DDS_Subscriber object on which the

operation is operated.in const DDS_DataReader a_datareader - a p o i n t e r t o t h e

DDS_DataReader, which is to be deleted.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionThis operation deletes a DDS_DataReader that belongs to the DDS_Subscriber.When the operation is called on a different DDS_Subscriber as used when theDDS_DataReader was created, the operation has no effect and returnsDDS_RETCODE_PRECONDITION_NOT_MET. The deletion of the DDS_DataReaderis not allowed if there are any DDS_ReadCondition or DDS_QueryConditionobjects that are attached to the DDS_DataReader, or when the DDS_DataReaderstill contains unreturned loans. In those cases the operation also returnsDDS_RETCODE_PRECONDITION_NOT_MET.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the DDS_DataReader is deleted.• DDS_RETCODE_ERROR - an internal error has occurred.

403API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on aninappropriate object.

• DDS_RETCODE_BAD_PARAMETER - the parameter a_datareader is not a validDDS_DataReader.

• DDS_RETCODE_ALREADY_DELETED - the DDS_Subscriber has already beendeleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_PRECONDITION_NOT_MET - the operation is called on a differentDDS_Subscriber as used when the DDS_DataReader was created, theDDS_DataReader contains one or more DDS_ReadCondition orDDS_QueryCondition objects or the DDS_DataReader still containsunreturned loans.

3.5.1.6 DDS_Subscriber_enable (inherited)

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t

DDS_Subscriber_enable (DDS_Subscriber _this);

DescriptionThis operation is inherited. See the Section 3.1.1, Class DDS_Entity (abstract), for ageneral description.

Behaviour when used in combination with group-scope coherent accessIn addition to the general description, the enable operation on a Subscriber hasspecial meaning in specific use cases. This applies only to Subscribers withPresentationQoSPolicy coherent_access s e t t o true w i thaccess_scope set to group.In this case the subscriber is always created in a disabled state, regardless of thefactory’s autoenable_created_entities setting. While the subscriber remainsdisabled, DataReaders can be created that will participate in coherent transactions ofthe subscriber (See Section 3.5.1.1, DDS_Subscriber_begin_access, and Section3.5.1.7, DDS_Subscriber_end_access, for more information).All DataReaders will also be created in a disabled state. Coherency with anaccess_scope of group requires data to be delivered as a transaction, atomically,to all eligible readers. Therefore data should not be delivered to any singleDataReader immediately after it is created, as usual, but only after the application

404API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

has finished creating all DataReaders for a given Subscriber. At this point, theapplication should enable the Subscriber which in turn enables all of itsDataReaders.

3.5.1.7 DDS_Subscriber_end_access

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Subscriber_end_access (DDS_Subscriber _this);

DescriptionThis operation indicates that the application will stop accessing a coherent and/orordered set of modifications that spans multiple DataReaders attached to thisDDS_Subscriber. This access must have been started by a matching call toDDS_Subscriber_begin_access.

Parametersin DDS_Subscriber _this - the DDS_Subscriber object on which the

operation is operated.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionIndicates that the application has finished accessing the data samples in DataReaderobjects managed by the Subscriber. This operation must be used to ‘close’ acorresponding begin_access. The operation will effectively unlock all of theSubscriber’s DataReader objects for incoming modifications, so it is important toinvoke it as quickly as possible to avoid an ever increasing backlog ofmodifications. After calling end_access the application should no longer accessany of the Data or SampleInfo elements returned from the sample-accessingoperations. Section 3.5.1.6, DDS_Subscriber_enable (inherited), contains additionalinformation about coherent access. This call must close a previous call to begin_access otherwise the operation willreturn the error PRECONDITION_NOT_MET.

405API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Return CodeWhen the operation returns:• DDS_RETCODE_OK - access to coherent/ordered data has successfully started.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter passed to the operation is NULL,

or is not pointing to any valid object.• DDS_RETCODE_ALREADY_DELETED - the DDS_Subscriber has already been

deleted.• DDS_RETCODE_PRECONDITION_NOT_MET - no matching call to begin_access

has been detected.

3.5.1.8 DDS_Subscriber_get_datareaders

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Subscriber_get_datareaders (DDS_Subscriber _this, DDS_DataReaderSeq *readers, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

DescriptionThis operation allows the application to access the DataReader objects that containsample s w i th t he spec i f i ed sample_states , view_states , a n dinstance_states.

Parametersin DDS_Subscriber _this - the DDS_Subscriber object on which the

operation is operated.inout DDS_DataReaderSeq *readers - a sequence which is used to pass the

list of all DataReaders that contain samples of the specified sample_states,view_states, and instance_states.

in const DDS_SampleStateMask sample_states - a mask, which selectsonly those readers that have samples with the desired sample states.

in const DDS_ViewStateMask view_states - a mask, which selects onlythose readers that have samples with the desired view states.

406API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

in const DDS_InstanceStateMask instance_states - a mask, whichselects only those readers that have samples with the desired instance states.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_ALREADY_DELETED , DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED or DDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionThis operation allows the application to access the DataReader objects that containsample s w i th t he spec i f i ed sample_states , view_states , a n dinstance_states.If the PresentationQosPolicy of the Subscriber to which the DataReaderbelongs has the access_scope set to ‘GROUP’, this operation should only beinvoked inside a begin_access/end_access block. Otherwise it will return theerror DDS_RETCODE_PRECONDITION_NOT_MET. Depending on the setting of the PresentationQoSPolicy (see Section 3.1.3.14 onpage 92), the returned collection of DataReader objects may be:• a ‘set’ containing each DataReader at most once in no specified order, • a ‘list’ containing each DataReader one or more times in a specific order. This difference is due to the fact that, in the second situation it is required to accesssamples belonging to different DataReader objects in a particular order. In this case,the application should process each DataReader in the same order it appears in the‘list’ and read or take exactly one sample from each DataReader. The patterns thatan application should use to access data is fully described in Section 3.1.3.14,DDS_PresentationQosPolicy.It is allowed to pre-allocate the DataReader sequence prior to invoking this function:• if the PresentationQosPolicy has access_scope set to ‘GROUP’ andordered_access set to TRUE, the ReaderList will never contain more than thepre-allocated number of elements. Pre-allocating ‘n’ Reader elements this way isconvenient in scenario’s where the application only intends to access the first ‘n’ordered samples. Otherwise the middleware would waste precious CPU cyclescomposing a list that will only partially be accessed.

• In all other cases, the ReaderList will re-allocated when it is not big enough toaccommodate a list describing all DataReaders that have matching samples.

407API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Return CodeWhen the operation returns:• DDS_RETCODE_OK - a list of DataReaders matching your description has

successfully been composed.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_Subscriber has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_NOT_ENABLED - the DDS_Subscriber is not enabled.• DDS_RETCODE_PRECONDITION_NOT_MET - the operation is not invoked inside abegin_access/end_access block as required by its QosPolicy settings.

3.5.1.9 DDS_Subscriber_get_default_datareader_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t

DDS_Subscriber_get_default_datareader_qos (DDS_Subscriber _this,

DDS_DataReaderQos *qos);

DescriptionThis operation gets the default QosPolicy settings of the DDS_DataReader.

Parametersin DDS_Subscriber _this - the DDS_Subscriber object on which the

operation is operated.inout DDS_DataReaderQos *qos - a pointer to the DDS_DataReaderQos

struct (provided by the application) in which the default QosPolicy settings forthe DDS_DataReader are written.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

408API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Detailed DescriptionThis operation gets the default QosPolicy settings of the DDS_DataReader (thatis the DDS_DataReaderQos) which is used for newly-created DDS_DataReaderobjects, in case the constant DDS_DATAREADER_QOS_DEFAULT is used. The defaultDDS_DataReaderQos is only used when the constant is supplied as parameterqos t o s p e c i f y t h e DDS_DataReaderQos i n t h eDDS_Subscriber_create_datareader operation. The application mustprovide the DDS_DataReaderQos struct in which the QosPolicy settings can bestored and pass the qos pointer to the operation. The operation writes the defaultQosPolicy settings to the struct pointed to by qos. Any settings in the struct areoverwritten.The values retrieved by this operation match the values specified on the lastsuccessful call to DDS_Subscriber_set_default_datareader_qos, or, if thecall was never made, the default values as specified for each QosPolicy setting asdefined in Table 5: on page 65.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the default DDS_DataReader QosPolicy settings of thisDDS_Subscriber have successfully been copied into the specifiedDDS_DataReaderQos parameter.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_Subscriber has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

3.5.1.10 DDS_Subscriber_get_listener

Synopsis#include <dds_dcps.h>struct DDS_SubscriberListener DDS_Subscriber_get_listener (DDS_Subscriber _this);

DescriptionThis operation allows access to a DDS_SubscriberListener.

409API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Parametersin DDS_Subscriber _this - the DDS_Subscriber object on which the

operation is operated.

Return Valuestruct DDS_SubscriberListener - r e s u l t i s a p o in t e r t o t h e

DDS_SubscriberListener attached to the DDS_Subscriber.

Detailed DescriptionThis operation allows access to a DDS_SubscriberListener attached to theDDS_Subscriber. When no DDS_SubscriberListener was attached to theDDS_Subscriber, the DDS_OBJECT_NIL pointer is returned.

3.5.1.11 DDS_Subscriber_get_participant

Synopsis#include <dds_dcps.h>DDS_DomainParticipant DDS_Subscriber_get_participant (DDS_Subscriber _this);

DescriptionThis operation returns the DDS_DomainParticipant associated with theDDS_Subscriber or the DDS_OBJECT_NIL pointer.

Parametersin DDS_Subscriber _this - the DDS_Subscriber object on which the

operation is operated.

Return ValueDDS_DomainParticipant - a pointer to the DDS_DomainParticipant

associated with the DDS_Subscriber or the DDS_OBJECT_NIL pointer.

Detailed DescriptionThis operation returns the DDS_DomainParticipant associated with theDDS_Subscriber. Note that there is exactly one DDS_DomainParticipantassociated with each DDS_Subscriber. When the DDS_Subscriber was alreadydeleted (there is no associated DDS_DomainParticipant any more), theDDS_OBJECT_NIL pointer is returned.

410API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

3.5.1.12 DDS_Subscriber_get_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Subscriber_get_qos (DDS_Subscriber _this, DDS_SubscriberQos *qos);

DescriptionThis operation allows access to the existing set of QoS policies for aDDS_Subscriber.

Parametersin DDS_Subscriber _this - the DDS_Subscriber object on which the

operation is operated.inout DDS_SubscriberQos *qos - a po in te r to the des t ina t ion

DDS_SubscriberQos struct in which the QosPolicy settings will be copied.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation al lows access to the exist ing set of QoS policies of aDDS_Subscriber on which this operation is used. This DDS_SubscriberQos isstored at the location pointed to by the qos parameter.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the existing set of QoS policy values applied to thisDDS_Subscriber has successfully been copied into the specifiedDDS_SubscriberQos parameter.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_Subscriber has already been

deleted.

411API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

3.5.1.13 DDS_Subscriber_get_status_changes (inherited)This operation is inherited and therefore not described here. See the classDDS_Entity for further explanation.

Synopsis#include <dds_dcps.h>DDS_StatusMask DDS_Subscriber_get_status_changes (DDS_Subscriber _this);

3.5.1.14 DDS_Subscriber_get_statuscondition (inherited)This operation is inherited and therefore not described here. See the classDDS_Entity for further explanation.

Synopsis#include <dds_dcps.h>DDS_StatusCondition DDS_Subscriber_get_statuscondition (DDS_Subscriber _this);

3.5.1.15 DDS_Subscriber_lookup_datareader

Synopsis#include <dds_dcps.h>DDS_DataReader DDS_Subscriber_lookup_datareader (DDS_Subscriber _this, const DDS_char *topic_name);

DescriptionThis operation returns a previously created DDS_DataReader belonging to theDDS_Subscriber which is attached to a DDS_Topic with the matchingtopic_name.

Parametersin DDS_Subscriber _this - the DDS_Subscriber object on which the

operation is operated.in const DDS_char *topic_name - the name of the DDS_Topic, which is

attached to the DDS_DataReader to look for.

412API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Return ValueDDS_DataReader - Return value is a pointer to the DDS_DataReader found.

When no such DDS_DataReader is found, the DDS_OBJECT_NIL pointer isreturned.

Detailed DescriptionThis operation returns a previously created DDS_DataReader belonging to theDDS_Subscriber which is attached to a DDS_Topic with the matchingtopic_name. When multiple DDS_DataReader objects (which satisfy the samecondition) exist, this operation will return one of them. It is not specified which one.This operation may be used on the built-in DDS_Subscriber, which returns thebuilt-in DDS_DataReader objects for the built-in DDS_Topics.

3.5.1.16 DDS_Subscriber_notify_datareaders

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Subscriber_notify_datareaders (DDS_Subscriber _this);

DescriptionThis operation invokes the DDS_DataReaderListener_on_data_availableoperation on DDS_DataReaderListener objects which are attached to thecontained DDS_DataReader entities having new, available data.

Parametersin DDS_Subscriber _this - the DDS_Subscriber object on which the

operation is operated.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR,DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETEDor DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation invokes the DDS_DataReaderListener_on_data_availableoperation on the DDS_DataReaderListener objects attached to containedDDS_DataReader entities that have received information, but which have not yetbeen processed by those DDS_DataReaders.

413API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

The DDS_Subscriber_notify_datareaders operation ignores the bit maskvalue of the individual DDS_DataReaderListener objects, even when theDDS_DATA_AVAILABLE_STATUS bit has not been set on a DDS_DataReader thatw h i c h h a s n e w, a v a i l a b l e d a t a . T h eDDS_DataReaderListener_on_data_available operation will still beinvoked, when the DATA_AVAILABLE_STATUS bit has not been set on aDataReader, b u t w i l l n o t p r o p a g a t e t o t h eDDS_DomainParticipantListener. When the DDS_DataReader has attached a NULL listener, the event will beconsumed and will not propagate to the DDS_DomainParticipantListener.(Remember that a NULL listener is regarded as a listener that handles all its events asa NOOP).

Return CodeWhen the operation returns:• DDS_RETCODE_OK - all appropriate listeners have been invoked• DDS_RETCODE_ERROR - an internal error has occurred• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object• DDS_RETCODE_ALREADY_DELETED - the DDS_Subscriber has already been

deleted• DDS_RETCODE_OUT_OF_RESOURCES - there are insufficient Data Distribution

Service resources to complete this operation

3.5.1.17 DDS_Subscriber_set_default_datareader_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Subscriber_set_default_datareader_qos (DDS_Subscriber _this, const DDS_DataReaderQos *qos);

DescriptionThis operation sets the default DDS_DataReaderQos of the DDS_DataReader.

Parametersin DDS_Subscriber _this - the DDS_Subscriber object on which the

operation is operated.

414API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

in const DDS_DataReaderQos *qos - the DDS_DataReaderQos struct,which contains the new default QosPolicy settings for the newly-createdDDS_DataReaders.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_UNSUPPORTED, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_INCONSISTENT_POLICY.

Detailed DescriptionThis operation sets the default DDS_DataReaderQos of the DDS_DataReader(that is the struct with the QosPolicy settings). This QosPolicy is used forne wly -c r ea t ed DDS_DataReader ob j e c t s i n c a se t he c ons t a n tDDS_DATAREADER_QOS_DEFAULT is used as parameter qos to specify theDDS_DataReaderQos in the DDS_Subscriber_create_datareaderoperation. This operation checks if the DDS_DataReaderQos is self consistent. If iti s n o t , t h e o p e r a t i o n h a s n o e f f e c t a nd r e t u r n sDDS_RETCODE_INCONSISTENT_POLICY.T h e v a l u e s s e t b y t h i s o p e r a t i o n a r e r e t u r n e d b yDDS_Subscriber_get_default_datareader_qos.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the new default DDS_DataReaderQos is set.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter qos is not a validDDS_DataReaderQos. It contains a QosPolicy setting with an invalidDDS_Duration_t value, an enum value that is outside its legal boundaries or asequence that has inconsistent memory settings.

• DDS_RETCODE_UNSUPPORTED - one or more of the selected QosPolicy valuesare currently not supported by OpenSplice.

• DDS_RETCODE_ALREADY_DELETED - the DDS_Subscriber has already beendeleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

415API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

• DDS_RETCODE_INCONSISTENT_POLICY - the parameter qos containsconflicting QosPolicy settings, e.g. a history depth that is higher than thespecified resource limits.

3.5.1.18 DDS_Subscriber_set_listener

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Subscriber_set_listener (DDS_Subscriber _this, const struct DDS_SubscriberListener *a_listener, const DDS_StatusMask mask);

DescriptionThis operation attaches a DDS_SubscriberListener to the DDS_Subscriber.

Parametersin DDS_Subscriber _this - the DDS_Subscriber object on which the

operation is operated.in const struct DDS_SubscriberListener *a_listener - a pointer to

the DDS_SubscriberListener instance, which will be attached to theDDS_Subscriber.

in const DDS_StatusMask mask - a bit-mask in which each bit enables theinvocation of the DDS_SubscriberListener for a certain status.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_UNSUPPORTED , DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation attaches a DDS_SubscriberListener to the DDS_Subscriber.Only one DDS_SubscriberListener can be attached to each DDS_Subscriber.If a DDS_SubscriberListener was already attached, the operation will replace itwith the new one. When a_listener is the DDS_OBJECT_NIL pointer, itrepresents a listener that is treated as a NOOP1 for all statuses activated in thebitmask.

1. Short for No-Operation, an instruction that peforms nothing at all.

416API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Communication StatusFor each communication status, the StatusChangedFlag flag is initially set toFALSE. It becomes TRUE whenever that communication status changes. For eachcommun ica t i on s t a t u s a c t i va t ed i n t he mask , t h e a s soc i a t e dDDS_SubscriberListener operation is invoked and the communication status isreset to FALSE, as the listener implicitly accesses the status which is passed as aparameter to that operation. The status is reset prior to calling the listener, so if theapplication calls the get_<status_name>_status from inside the listener it willsee the status already reset. An exception to this rule is the DDS_OBJECT_NILlistener, which does not reset the communication statuses for which it is invoked. The following statuses are applicable to the DDS_SubscriberListener:• DDS_REQUESTED_DEADLINE_MISSED_STATUS (propagated)• DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS (propagated)• DDS_SAMPLE_LOST_STATUS (propagated)• DDS_SAMPLE_REJECTED_STATUS (propagated)• DDS_DATA_AVAILABLE_STATUS (propagated)• DDS_LIVELINESS_CHANGED_STATUS (propagated)• DDS_SUBSCRIPTION_MATCHED_STATUS (propagated).• DDS_DATA_ON_READERS_STATUS.Be aware that the DDS_SUBSCRIPTION_MATCHED_STATUS is not applicable whenthe infrastructure does not have the information available to determine connectivity.This is the case when OpenSplice is configured not to maintain discoveryinformation in the Networking Service. (See also the description of theNetworkService/Discovery[@enabled] attribute in section 4.4.1.6.1on page 244 of the Deployment Guide.) In this case the operation will returnDDS_RETCODE_UNSUPPORTED.Status bits are declared as a constant and can be used by the application in an ORoperation to create a tailored mask. The special constant DDS_STATUS_MASK_NONEcan be used to indicate that the created entity should not respond to any of itsavailable statuses. The DDS will therefore attempt to propagate these statuses to itsfactory. The special constant STATUS_MASK_ANY_V1_2 can be used to select allapplicable statuses specified in the “Data Distribution Service for Real-timeSystems Version 1.2” specification.

Status PropagationThe Data Distribution Service will trigger the most specific and relevant Listener.In other words, in case a communication status is also activated on theDDS_DataReaderListener o f a conta ined DDS_DataReader, the

417API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

DDS_DataReaderListener on that contained DDS_DataReader is invokedinstead of the DDS_SubscriberListener. This means that a status change on acontained DDS_DataReader only invokes the DDS_SubscriberListener if thecontained DDS_DataReader itself does not handle the trigger event generated bythe status change. In case a communica t ion s ta tus i s not ac t iva ted in the mask o f theDDS_SubscriberListener, the DDS_DomainParticipantListener of thecontaining DDS_DomainParticipant is invoked (if attached and activated for thestatus that occurred). This allows the application to set a default behaviour in theDDS_DomainParticipantListener o f t h e c o n t a i n i n gDDS_DomainParticipant and a DDS_Subscriber specific behaviour whenneeded. In case the DDS_DomainParticipantListener is also not attached orthe communication status is not activated in its mask, the application is not notifiedof the change.The s t a t u se s DDS_DATA_ON_READERS_STATUS a n d DDS_DATA_AVAILABLE_STATUS are “Read Communication Statuses” and are an exception toall other plain communication statuses: they have no corresponding status structurethat can be obtained with a get_<status_name>_status operation and they aremutually exclusive. When new information becomes available to a DataReader, theData Distribution Service will f irst look in an attached and activatedDDS_SubscriberListener or DDS_DomainParticipantListener (in thato r d e r ) f o r t h e DDS_DATA_ON_READERS_STATUS . I n c a s e t h eDDS_DATA_ON_READERS_STATUS can not be handled, the Data DistributionService will look in an attached and activated DDS_DataReaderListener,DDS_SubscriberListener or DDS_DomainParticipantListener for theDDS_DATA_AVAILABLE_STATUS (in that order).

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the DDS_SubscriberListener is attached.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_UNSUPPORTED - a status was selected that cannot be supported

because the infrastructure does not maintain the required connectivityinformation.

• DDS_RETCODE_ALREADY_DELETED - the DDS_Subscriber has already beendeleted.

418API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

3.5.1.19 DDS_Subscriber_set_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_Subscriber_set_qos (DDS_Subscriber _this, const DDS_SubscriberQos *qos);

DescriptionThis operation replaces the exist ing set of QosPolicy set t ings for aDDS_Subscriber.

Parametersin DDS_Subscriber _this - the DDS_Subscriber object on which the

operation is operated.in const DDS_SubscriberQos *qos - contain the new set of QosPolicy

settings for the DDS_Subscriber.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_UNSUPPORTED, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_ IMMUTABLE_POLICY o rDDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionThis operation replaces the exist ing set of QosPolicy set t ings for aDDS_Subscriber. The parameter qos must contain the QosPolicy settings whichis checked for self-consistency and mutability. When the application tries to changea QosPolicy setting for an enabled DDS_Subscriber, which can only be setbefore the DDS_Subscriber is enabled, the operation will fail and aDDS_RETCODE_IMMUTABLE_POLICY is returned. In other words, the applicationmust provide the presently set QosPolicy settings in case of the immutableQosPolicy settings. Only the mutable QosPolicy settings can be changed. Whenqos contains conflicting QosPolicy settings (not self-consistent), the operationwill fail and a RETCODE_INCONSISTENT_POLICY is returned.

419API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

The set of QosPolicy settings specified by the qos parameter are applied on top ofthe existing QoS, replacing the values of any policies previously set (provided, theoperation returned DDS_RETCODE_OK). If one or more of the partitions in the QoSstructure have insufficient access rights configured then the set_qos function willfail with a DDS_RETCODE_PRECONDITION_NOT_MET error code.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the new DDS_SubscriberQos is set.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter qos is not a validDDS_SubscriberQos. It contains a QosPolicy setting with an enum valuethat is outside its legal boundaries or a sequence that has inconsistent memorysettings.

• DDS_RETCODE_UNSUPPORTED - one or more of the selected QosPolicy values arecurrently not supported by OpenSplice.

• DDS_RETCODE_ALREADY_DELETED - the DDS_Subscriber has already beendeleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_IMMUTABLE_POLICY - the parameter qos contains animmutable QosPolicy setting with a different value than set during enabling ofthe DDS_Subscriber.

• DDS_RETCODE_PRECONDITION_NOT_MET - returned when insufficient accessrights exist for the partition(s) listed in the QoS structure.

3.5.2 Subscription Type Specific Classes“Subscription type specific classes” contains the generic class and the generateddata type specific classes. For each data type, a data type specific class<NameSpace>_<type>DataReader is generated (based on IDL) by calling thepre-processor. In case of data type Foo (this also applies to other types), defined inthe module SPACE; “Subscription type specific classes” contains the followingclasses:This paragraph describes the generic DDS_DataReader class and the derivedapplication type specific <NameSpace>_<type>DataReader classes whichtogether implement the application subscription interface. For each application type,u se d a s DDS_Topic d a t a t ype , t he p r e -p roce s s o r gene ra t e s a

420API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

<NameSpace>_<type>DataReader class from an IDL type description. TheSPACE_FooDataReader class that would be generated by the pre-processor for af i c t i o na l t yp e Foo ( d e f i n e d i n t h e m o d u l e SPACE ) d e s c r i b e s t h e<NameSpace>_<type>DataReader classes.

3.5.2.1 Class DDS_DataReader (abstract)A DDS_DataReader allows the application:• to declare data it wishes to receive (i.e., make a subscription)• to access data received by the associated DDS_Subscriber.A DDS_DataReader refers to exactly one DDS_TopicDescription (either aDDS_Topic, a DDS_ContentFilteredTopic or a DDS_MultiTopic) thatidentifies the samples to be read. The DDS_DataReader may give access to severalinstances of the data type, which are distinguished from each other by their key.DDS_DataReader is an abstract class. It is specialized for each particularapplication data type. For a fictional application data type “Foo” the specializedclass would be SPACE_FooDataReader.The interface description of this class is as follows:

/* * interface DDS_DataReader *//* * inherited from class DDS_Entity *//* DDS_StatusCondition * DDS_DataReader_get_statuscondition * (DDS_DataReader _this); *//* DDS_StatusMask * DDS_DataReader_get_status_changes * (DDS_DataReader _this); *//* DDS_ReturnCode_t * DDS_DataReader_enable * (DDS_DataReader _this); *//* * abstract operations * (implemented in the data type specific DDS_DataReader) *//* DDS_ReturnCode_t * DDS_DataReader_read * (DDS_DataReader _this, * DDS_sequence_<data> *data_values, * DDS_SampleInfoSeq *info_seq,

421API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

* const DDS_long max_samples, * const DDS_SampleStateMask sample_states, * const DDS_ViewStateMask view_states, * const DDS_InstanceStateMask instance_states); *//* DDS_ReturnCode_t * DDS_DataReader_take * (DDS_DataReader _this, * DDS_sequence_<data> *data_values, * DDS_SampleInfoSeq *info_seq, * const DDS_long max_samples, * const DDS_SampleStateMask sample_states, * const DDS_ViewStateMask view_states, * const DDS_InstanceStateMask instance_states); *//* DDS_ReturnCode_t * DDS_DataReader_read_w_condition * (DDS_DataReader _this, * DDS_sequence_<data> *data_values, * DDS_SampleInfoSeq *info_seq, * const DDS_long max_samples, * const DDS_ReadCondition a_condition); *//* DDS_ReturnCode_t * DDS_DataReader_take_w_condition * (DDS_DataReader _this, * DDS_sequence_<data> *data_values, * DDS_SampleInfoSeq *info_seq, * const DDS_long max_samples, * const DDS_ReadCondition a_condition); *//* DDS_ReturnCode_t * DDS_DataReader_read_next_sample * (DDS_DataReader _this, * <data> *data_values, * DDS_SampleInfo *sample_info); *//* DDS_ReturnCode_t * DDS_DataReader_take_next_sample * (DDS_DataReader _this, * <data> *data_values, * DDS_SampleInfo *sample_info); *//* DDS_ReturnCode_t * DDS_DataReader_read_instance * (DDS_DataReader _this, * DDS_sequence_<data> *data_values, * DDS_SampleInfoSeq *info_seq, * const DDS_long max_samples, * const DDS_InstanceHandle_t a_handle,

422API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

* const DDS_SampleStateMask sample_states, * const DDS_ViewStateMask view_states, * const DDS_InstanceStateMask instance_states); *//* DDS_ReturnCode_t * DDS_DataReader_take_instance * (DDS_DataReader _this, * DDS_sequence_<data> *data_values, * DDS_SampleInfoSeq *info_seq, * const DDS_long max_samples, * const DDS_InstanceHandle_t a_handle, * const DDS_SampleStateMask sample_states, * const DDS_ViewStateMask view_states, * const DDS_InstanceStateMask instance_states); *//* DDS_ReturnCode_t * DDS_DataReader_read_next_instance * (DDS_DataReader _this, * DDS_sequence_<data> *data_values, * DDS_SampleInfoSeq *info_seq, * const DDS_long max_samples, * const DDS_InstanceHandle_t a_handle, * const DDS_SampleStateMask sample_states, * const DDS_ViewStateMask view_states, * const DDS_InstanceStateMask instance_states); *//* DDS_ReturnCode_t * DDS_DataReader_take_next_instance * (DDS_DataReader _this, * DDS_sequence_<data> *data_values, * DDS_SampleInfoSeq *info_seq, * const DDS_long max_samples, * const DDS_InstanceHandle_t a_handle, * const DDS_SampleStateMask sample_states, * const DDS_ViewStateMask view_states, * const DDS_InstanceStateMask instance_states); *//* DDS_ReturnCode_t * DDS_DataReader_read_next_instance_w_condition * (DDS_DataReader _this, * DDS_sequence_<data> *data_values, * DDS_SampleInfoSeq *info_seq, * const DDS_long max_samples, * const DDS_InstanceHandle_t a_handle, * const DDS_ReadCondition a_condition); *//* DDS_ReturnCode_t * DDS_DataReader_take_next_instance_w_condition * (DDS_DataReader _this, * DDS_sequence_<data> *data_values,

423API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

* DDS_SampleInfoSeq *info_seq, * const DDS_long max_samples, * const DDS_InstanceHandle_t a_handle, * const DDS_ReadCondition a_condition); *//* DDS_ReturnCode_t * DDS_DataReader_return_loan * (DDS_DataReader _this, * DDS_sequence_<data> *data_values, * DDS_SampleInfoSeq *info_seq); *//* DDS_ReturnCode_t * DDS_DataReader_get_key_value * (DDS_DataReader _this, * <data> *key_holder, * const DDS_InstanceHandle_t handle); *//* DDS_InstanceHandle_t * DDS_DataReader_lookup_instance */ (DDS_DataReader _this, * <data> *instance_data);/* * implemented API operations */

DDS_ReadCondition DDS_DataReader_create_readcondition (DDS_DataReader _this, const DDS_SampleStateMask sample_states,

const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

DDS_QueryCondition DDS_DataReader_create_querycondition (DDS_DataReader _this, const DDS_SampleStateMask sample_states,

const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states, const DDS_char *query_expression, const DDS_StringSeq *query_parameters);

DDS_ReturnCode_t DDS_DataReader_delete_readcondition (DDS_DataReader _this, const DDS_ReadCondition a_condition);

DDS_ReturnCode_t DDS_DataReader_delete_contained_entities (DDS_DataReader _this);

DDS_ReturnCode_t

424API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

DDS_DataReader_set_qos (DDS_DataReader _this, const DDS_DataReaderQos *qos);

DDS_ReturnCode_t DDS_DataReader_get_qos (DDS_DataReader _this, DDS_DataReaderQos *qos);

DDS_ReturnCode_t DDS_DataReader_set_listener (DDS_DataReader _this, const struct DDS_DataReaderListener *a_listener, const DDS_StatusMask mask);

struct DDS_DataReaderListener DDS_DataReader_get_listener (DDS_DataReader _this);

DDS_TopicDescription DDS_DataReader_get_topicdescription (DDS_DataReader _this);

DDS_Subscriber DDS_DataReader_get_subscriber (DDS_DataReader _this);

DDS_ReturnCode_t DDS_DataReader_get_sample_rejected_status (DDS_DataReader _this, DDS_SampleRejectedStatus *status);

DDS_ReturnCode_t DDS_DataReader_get_liveliness_changed_status (DDS_DataReader _this, DDS_LivelinessChangedStatus *status);

DDS_ReturnCode_t DDS_DataReader_get_requested_deadline_missed_status (DDS_DataReader _this, DDS_RequestedDeadlineMissedStatus *status);

DDS_ReturnCode_t DDS_DataReader_get_requested_incompatible_qos_status (DDS_DataReader _this, DDS_RequestedIncompatibleQosStatus *status);

DDS_ReturnCode_t DDS_DataReader_get_subscription_matched_status (DDS_DataReader _this,

425API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

DDS_SubscriptionMatchedStatus *status);

DDS_ReturnCode_t DDS_DataReader_get_sample_lost_status (DDS_DataReader _this, DDS_SampleLostStatus *status);

DDS_ReturnCode_t DDS_DataReader_wait_for_historical_data (DDS_DataReader _this, const DDS_Duration_t *max_wait);

DDS_ReturnCode_t DDS_DataReader_get_matched_publications (DDS_DataReader _this, DDS_InstanceHandleSeq *publication_handles);

DDS_ReturnCode_t DDS_DataReader_get_matched_publication_data (DDS_DataReader _this, DDS_PublicationBuiltinTopicData *publication_data,

const DDS_InstanceHandle_t publication_handle);

DDS_DataReaderView DDS_DataReader_create_view (DDS_DataReader _this const DDS_DataReaderViewQos* qos);

DDS_ReturnCode_t DDS_DataReader_delete_view (DDS_DataReader _this, const DDS_DataReaderView a_view);

DDS_ReturnCode_t DDS_DataReader_get_default_datareaderview_qos (DDS_DataReader _this, DDS_DataReaderViewQos* qos);

DDS_ReturnCode_t DDS_DataReader_set_default_datareaderview_qos (DDS_DataReader _this, DDS_DataReaderViewQos* qos);

The following paragraphs describe the usage of all DDS_DataReader operations.The inherited operations are listed but not fully described because they are notimplemented in this class. The full description of these operations is given in theclasses from which they are inherited. The abstract operations are listed but not fully

426API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

described because they are not implemented in this specific class. The fulldescription of these operations is located in the subclasses that contain the data typespecific implementation of these operations.

3.5.2.2 DDS_DataReader_create_querycondition

Synopsis#include <dds_dcps.h>DDS_QueryCondition DDS_DataReader_create_querycondition (DDS_DataReader _this, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states, const DDS_char *query_expression, const DDS_StringSeq *query_parameters);

DescriptionThis operation creates a new DDS_QueryCondition for the DDS_DataReader.

Parametersin DDS_DataReader _this - the DDS_DataReader object on which the

operation is operated.in const DDS_SampleStateMask sample_states - a mask, which selects

only those samples with the desired sample states.in const DDS_ViewStateMask view_states - a mask, which selects only

those samples with the desired view states.in const DDS_InstanceStateMask instance_states - a mask, which

selects only those samples with the desired instance states.in const DDS_char *query_expression - the query string, which must be a

subset of the SQL query language as specified in Appendix H, DCPS Queriesand Filters.

in const DDS_StringSeq *query_parameters - a sequence of strings whichare the parameters used in the SQL query string (i.e., the “%n” tokens in theexpression). The number of values in query_parameters must be equal orgreater than the highest referenced %n token in the query_expression (e.g.i f %1 and %8 a re used as parameter in the query_expression, thequery_parameters should at least contain n+1 = 9 values).

Return ValueDDS_QueryCondition - Result value is a pointer to the DDS_QueryCondition.

When the operation fails, the DDS_OBJECT_NIL pointer is returned.

427

API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Detailed DescriptionThis operation creates a new DDS_QueryCondition for the DDS_DataReader.The returned DDS_QueryCondition is attached (and belongs) to theDDS_DataReader. When the operation fails, the DDS_OBJECT_NIL pointer isr e t u r n e d . To d e l e t e t h e DDS_QueryCondition t h e o p e r a t i o nDDS_DataReader_delete_readcondition or DDS_DataReader_delete_contained_entities must be used.

State MasksThe result of the DDS_QueryCondition also depends on the selection of samplesdetermined by three masks:• sample_states is the mask, which selects only those samples with the desired

sample states DDS_READ_SAMPLE_STATE, DDS_NOT_READ_SAMPLE_STATE orboth

• view_states is the mask, which selects only those samples with the desiredview states DDS_NEW_VIEW_STATE, DDS_NOT_NEW_VIEW_STATE or both

• instance_states is the mask, which selects only those samples with thedesired instance states DDS_ALIVE_INSTANCE_STATE, DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE, DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE or a combination of these.

SQL expressionThe SQL query string is set by query_expression which must be a subset of theSQL query language. In this query expression, parameters may be used, which mustbe set in the sequence of strings defined by the parameter query_parameters. Aparameter is a string which can define an integer, float, string or enumeration. Thenumber of values in query_parameters must be equal or greater than the highestreferenced %n token in the query_expression (e.g. if %1 and %8 are used asparameter in the query_expression, the query_parameters should at leastcontain n+1 = 9 values).

3.5.2.3 DDS_DataReader_create_readcondition

Synopsis#include <dds_dcps.h>DDS_ReadCondition DDS_DataReader_create_readcondition (DDS_DataReader _this, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

428API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

DescriptionThis operation creates a new DDS_ReadCondition for the DDS_DataReader.

Parametersin DDS_DataReader _this - the DDS_DataReader object on which the

operation is operated.in const DDS_SampleStateMask sample_states - a mask, which selects

only those samples with the desired sample states.in const DDS_ViewStateMask view_states - a mask, which selects only

those samples with the desired view states.in const DDS_InstanceStateMask instance_states - a mask, which

selects only those samples with the desired instance states.

Return ValueDDS_ReadCondition - Result value is a pointer to the DDS_ReadCondition.

When the operation fails, the DDS_OBJECT_NIL pointer is returned.

Detailed DescriptionThis operation creates a new DDS_ReadCondition for the DDS_DataReader. Thereturned DDS_ReadCondition is attached (and belongs) to the DDS_DataReader.When the operation fails, the DDS_OBJECT_NIL pointer is returned. To delete theDDS_ReadCondition t he ope r a t i on DDS_DataReader_delete_readcondition or DDS_DataReader_delete_contained_entities must beused.

State MasksThe result of the DDS_ReadCondition depends on the selection of samplesdetermined by three masks:• sample_states is the mask, which selects only those samples with the desired

sample states DDS_READ_SAMPLE_STATE, DDS_NOT_READ_SAMPLE_STATE orboth

• view_states is the mask, which selects only those samples with the desiredview states DDS_NEW_VIEW_STATE, DDS_NOT_NEW_VIEW_STATE or both

• instance_states is the mask, which selects only those samples with thedesired instance states DDS_ALIVE_INSTANCE_STATE, DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE, DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE or a combination of these.

429API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

3.5.2.4 DDS_DataReader_create_view

Synopsis#include <dds_dcps.h>DDS_DataReaderView DDS_DataReader_create_view (DDS_DataReader _this, const DDS_DataReaderViewQos* qos);

DescriptionThis operation creates a DataReaderView with the desired QosPolicy settings.

Parametersin DDS_DataReader _this - the DDS_DataReader object on which the

operation is operated.in const DDS_DataReaderViewQos* qos - the QosPolicy settings for the

DataReaderView.

Return ValueDDS_DataReaderView - Pointer to the newly-created DataReaderView. In case of

error, the NULL pointer is returned.

Detailed DescriptionThis operation creates a DataReaderView with the desired QosPolicy settings. Incase the QosPolicy is invalid, a NULL pointer is returned. The convenience macroDDS_DATAREADERVIEW_QOS_DEFAULT can be used as parameter qos, to create aDataReaderView with the default DataReaderViewQos as set in the DataReader.

Application Data TypeThe DataReaderView returned by this operation is an object of a derived class,specific to the data type associated with the Topic. For each application-defined datatype <type> there is a class <type>DataReaderView generated by calling thepre-processor. This data type specific class extends DataReaderView and containsthe operations to read and take data of data type <type>. The typed operations of a DataReaderView exactly mimic those of the DataReaderfrom which it is created.

3.5.2.5 DDS_DataReader_delete_contained_entities

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t

430API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

DDS_DataReader_delete_contained_entities (DDS_DataReader _this);

DescriptionThis operation deletes all the DDS_Entity objects that were created by means ofone of the “create_” operations on the DDS_DataReader.

Parametersin DDS_DataReader _this - the DDS_DataReader object on which the

operation is operated.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_ALREADY_DELETED , DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionThis operation deletes all the DDS_Entity objects that were created by means ofone of the “create_” operations on the DDS_DataReader. In other words, itdeletes all DDS_QueryCondition and DDS_ReadCondition objects containedby the DDS_DataReader.

NOTE: The operation will return DDS_PRECONDITION_NOT_MET if the any of thecontained entities is in a state where it cannot be deleted. In such cases, theoperation does not roll back any entity deletions performed prior to the detection ofthe problem.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the contained DDS_Entity objects are deleted and the

application may delete the DDS_DataReader.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_DataReader has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

431API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

• DDS_RETCODE_PRECONDITION_NOT_MET - one or more of the contained entitiesare in a state where they cannot be deleted.

3.5.2.6 DDS_DataReader_delete_readcondition

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReader_delete_readcondition (DDS_DataReader _this, const DDS_ReadCondition a_condition);

DescriptionThis operation deletes a DDS_ReadCondition or DDS_QueryCondition whichis attached to the DDS_DataReader.

Parametersin DDS_DataReader _this - the DDS_DataReader object on which the

operation is operated.in const DDS_ReadCondition a_condition - a pointer to the

DDS_ReadCondition or DDS_QueryCondition which is to be deleted.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionThis operation deletes a DDS_ReadCondition or DDS_QueryCondition whichis attached to the DDS_DataReader. Since a DDS_QueryCondition is aspecialized DDS_ReadCondition, the operation can also be used to delete aDDS_QueryCondition. A DDS_ReadCondition or DDS_QueryConditioncannot be deleted when it is not attached to this DDS_DataReader. When theoperation is called on a DDS_ReadCondition or DDS_QueryCondition whichwas no t a t t ached to t h i s DDS_DataReader , t he ope ra t ion r e tu rnsDDS_RETCODE_PRECONDITION_NOT_MET.

Return CodeWhen the operation returns:

432API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

• DDS_RETCODE_OK - the DDS_ReadCondition or DDS_QueryCondition isdeleted.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter a_condition is not a validDDS_ReadCondition.

• DDS_RETCODE_ALREADY_DELETED - the DDS_DataReader has already beendeleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_PRECONDITION_NOT_MET - the operation is called on a differentDDS_DataReader, as used when the DDS_ReadCondition orDDS_QueryCondition was created.

3.5.2.7 DDS_DataReader_delete_view

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReader_delete_view (DDS_DataReader _this, DDS_DataReaderView a_view);

DescriptionThis operation deletes a DataReaderView that belongs to the DataReader.

Parametersin DDS_DataReader _this - the DDS_DataReader object on which the

operation is operated.in DDS_DataReaderView a_view - a pointer to the DataReaderView which is

to be deleted.

Return ValueDDS_ReturnCode_t - Possible return codes of the operation are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_BAD_PARAMETER,DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES,DDS_RETCODE_PRECONDITION_NOT_MET.

433API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Detailed DescriptionThis operation deletes the DataReaderView from the DataReader.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the DataReaderView is deleted.• DDS_RETCODE_ERROR - an internal error occurred.• DDS_RETCODE_BAD_PARAMETER - the DataReaderView parameter is invalid.• DDS_RETCODE_ALREADY_DELETED - the DataReader has already been deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the data distribution service ran out of

resources to complete this operation.• DDS_RETCODE_PRECONDITION_NOT_MET - the DataReaderView is not

associated with this DataReader, or the DataReaderView still contains one ormore ReadCondition or QueryCondition objects or an unreturned loan.

3.5.2.8 DDS_DataReader_enable (inherited)This operation is inherited and therefore not described here. See the classDDS_Entity for further explanation.

Synopsis#include <dds_dcps.h>

DDS_ReturnCode_t DDS_DataReader_enable (DDS_DataReader _this);

3.5.2.9 DDS_DataReader_get_default_datareaderview_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReader_get_default_datareaderview_qos (DDS_DataReader _this, DDS_DataReaderViewQos* qos);

DescriptionThis operation gets the default QosPolicy settings of the DataReaderView.

Parametersin DDS_DataReader _this - the DDS_DataReader object on which the

operation is operated.

434API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

inout DataReaderViewQos* qos - a r e f e r e n c e t o t h eDDS_DataReaderViewQos struct in which the default QosPolicy settings willbe stored.

Return ValueDDS_ReturnCode_t - Possible return codes of the operation are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation gets the default QosPolicy settings of the DDS_DataReaderView,which are used for newly-created DDS_DataReaderView objects in case theconstant DDS_DATAREADERVIEW_QOS_DEFAULT is used.The values retrieved by this call match the values specified on the last successfulcall to DDS_DataReader_set_default_datareaderview_qos, or, if this callwas never made, the default values as specified in Table 5: on page 65.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the default DDS_DataReaderViewQosPolicy settings of

this DDS_DataReader have successfully been copied into the providedDDS_DataReaderViewQos parameter.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ALREADY_DELETED - the DDS_DataReader has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the data distribution service ran out of

resources to complete this operation.

3.5.2.10 DDS_DataReader_get_key_value (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReader class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataReader class.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t

DDS_DataReader_get_key_value(DDS_DataReader _this,

<data> *key_holder,

435API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

const DDS_InstanceHandle_t handle);

3.5.2.11 DDS_DataReader_get_listener

Synopsis#include <dds_dcps.h>struct DDS_DataReaderListener DDS_DataReader_get_listener (DDS_DataReader _this);

DescriptionThis operation allows access to a DDS_DataReaderListener.

Parametersin DDS_DataReader _this - the DDS_DataReader object on which the

operation is operated.

Return Valuestruct DDS_DataReaderListener - r e s u l t i s a p o in t e r t o t h e

DDS_DataReaderListener attached to the DDS_DataReader.

Detailed DescriptionThis operation allows access to a DDS_DataReaderListener attached to theDDS_DataReader. When no DDS_DataReaderListener was attached to theDDS_DataReader, the DDS_OBJECT_NIL pointer is returned.

3.5.2.12 DDS_DataReader_get_liveliness_changed_status

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReader_get_liveliness_changed_status (DDS_DataReader _this, DDS_LivelinessChangedStatus *status);

DescriptionThis operation obtains the DDS_LivelinessChangedStatus struct of theDDS_DataReader.

Parametersin DDS_DataReader _this - the DDS_DataReader object on which the

operation is operated.

436API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

inout DDS_LivelinessChangedStatus *status - the contents of theDDS_LivelinessChangedStatus struct of the DDS_DataReader will becopied into the location specified by status.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:DDS_RETCODE_OK , DDS_RETCODE_ERROR , DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation obtains the DDS_LivelinessChangedStatus struct of theDDS_DataReader. This struct contains the information whether the liveliness ofone or more DDS_DataWriter objects that were writing instances read by theDDS_DataReader has changed. In other words, some DDS_DataWriter havebecome “alive” or “not alive”.The DDS_LivelinessChangedStatus can also be monitored using aDDS_DataReaderListener or by using the associated DDS_StatusCondition.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the current DDS_LivelinessChangedStatus of thisDDS_DataReader has successfully been copied into the specified statusparameter.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_DataReader has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

3.5.2.13 DDS_DataReader_get_matched_publication_data

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReader_get_matched_publication_data (DDS_DataReader _this, DDS_PublicationBuiltinTopicData *publication_data, const DDS_InstanceHandle_t publication_handle);

437API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

DescriptionThis operation retrieves information on the specified publication that is currently“associated” with the DDS_DataReader.

Parametersin DDS_DataReader _this - the DDS_DataReader object on which the

operation is operated.inout DDS_PublicationBuiltinTopicData *publication_data - a

pointer to the sample in which the information about the specified publication isto be stored.

in const DDS_InstanceHandle_t publication_handle - a handle to thepublication whose information needs to be retrieved.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:DDS_RETCODE_OK , DDS_RETCODE_ERROR , DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_UNSUPPORTED, DDS_RETCODE_ALREADY_DELETED,DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_NOT_ENABLED.

Detailed DescriptionThis operation retrieves information on the specified publication that is currently“associated” with the DDS_DataReader. That is, a publication with a matchingTopic and compatible QoS that the application has not indicated should be“ignored” by means of the DDS_DomainParticipant_ignore_publicationoperation.The publication_handle must correspond to a publication currently associatedwith the DDS_DataReader, otherwise the operation will fail and returnDDS_RETCODE_BAD_PARAMETER . The operat ion DDS_DataReader_get_matched_publications can be used to find the publications that arecurrently matched with the DDS_DataReader.The operation may also fail if the infrastructure does not hold the informationnecessary to fill in the publication_data. This is the case when OpenSplice isconfigured not to maintain discovery information in the Networking Service. (Seealso the description of the NetworkService/Discovery[@enabled]attribute in section 4.4.1.6.1 on page 244 of the Deployment Guide.) In thiscase the operation will return DDS_RETCODE_UNSUPPORTED.

Return CodeWhen the operation returns:

438API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

• DDS_RETCODE_OK - the information on the specified publication has successfullybeen retrieved.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_UNSUPPORTED - OpenSplice is configured not to maintain the

information about “associated” publications.• DDS_RETCODE_ALREADY_DELETED - the DDS_DataReader has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_NOT_ENABLED - the DDS_DataReader is not enabled.

3.5.2.14 DDS_DataReader_get_matched_publications

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReader_get_matched_publications (DDS_DataReader _this, DDS_InstanceHandleSeq *publication_handles);

DescriptionThis operation retrieves the list of publications currently "associated" with theDDS_DataReader.

Parametersin DDS_DataReader _this - the DDS_DataReader object on which the

operation is operated.inout DDS_InstanceHandleSeq *publication_handles - a sequence

which is used to pass the list of all associated publications.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:DDS_RETCODE_OK , DDS_RETCODE_ERROR , DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_UNSUPPORTED, DDS_RETCODE_ALREADY_DELETED,DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_NOT_ENABLED.

439API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Detailed DescriptionThis operation retrieves the list of publications currently "associated" with theDDS_DataReader. That is, subscriptions that have a matching Topic andcompatible QoS that the application has not indicated should be “ignored” by meansof the DDS_DomainParticipant_ignore_publication operation.The publication_handles sequence and its buffer may be pre-allocated by theapplication and therefore must either be re-used in a subsequent invocation of theDDS_DataReader_get_matched_publications operation or be released bycalling DDS_free on the returned publication_handles. If the pre-allocatedsequence is not big enough to hold the number of associated publications, thesequence will automatically be (re-)allocated to fit the required size. The handles returned in the publication_handles sequence are the ones that areused by the DDS implementation to locally identify the corresponding matchedDataWriter entities. You can access more detailed information about a particularp u b l i c a t i o n b y p a s s i n g i t s publication_handle t o e i t h e r t h eDDS_DataReader_get_matched_publication_data operation or to theDDS_PublicationBuiltinTopicDataDataReader_read_instanceoperation on the built-in reader for the “DCPSPublication” topic. Be aware that since DDS_InstanceHandle_t is an opaque datatype, it does notnecessarily mean that the handles obtained from the DDS_DataReader_get_matched_publications operation have the same value as the ones thatappear in the instance_handle field of the DDS_SampleInfo when retrievingthe publication info through corresponding "DCPSPublication" built-in reader. Youcan’t just compare two handles to determine whether they represent the samepublication. If you want to know whether two handles actually do represent thesame publ ica t ion , use both handles to re t r ieve the i r cor respondingDDS_PublicationBuiltinTopicData samples and then compare the key fieldof both samples.The operation may fail if the infrastructure does not locally maintain theconnectivity information. This is the case when OpenSplice is configured not tomaintain discovery information in the Networking Service. (See also the descriptionof the NetworkService/Discovery[@enabled] attribute in section4.4.1.6.1 on page 244 of the Deployment Guide.) In this case the operation willreturn DDS_RETCODE_UNSUPPORTED.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the list of associated publications has successfully been

obtained.• DDS_RETCODE_ERROR - an internal error has occurred.

440API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on aninappropriate object.

• DDS_RETCODE_UNSUPPORTED - OpenSplice is configured not to maintain theinformation about “associated” publications.

• DDS_RETCODE_ALREADY_DELETED - the DDS_DataReader has already beendeleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_NOT_ENABLED - the DDS_DataReader is not enabled.

3.5.2.15 DDS_DataReader_get_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReader_get_qos (DDS_DataReader _this, DDS_DataReaderQos *qos);

DescriptionThis operation allows access to the existing set of QoS policies for aDDS_DataReader.

Parametersin DDS_DataReader _this - the DDS_DataReader object on which the

operation is operated.inout DDS_DataReaderQos *qos - a reference to the dest inat ion

DDS_DataReaderQos struct in which the QosPolicy settings will be copied.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:DDS_RETCODE_OK , DDS_RETCODE_ERROR , DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation al lows access to the exist ing set of QoS policies of aDDS_DataReader on which this operation is used. This DDS_DataReaderQos isstored at the location pointed to by the qos parameter.

441API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the existing set of QoS policy values applied to thisDDS_DataReader has successfully been copied into the specifiedDDS_DataReaderQos parameter.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_DataReader has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

3.5.2.16 DDS_DataReader_get_requested_deadline_missed_status

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReader_get_requested_deadline_missed_status (DDS_DataReader _this, DDS_RequestedDeadlineMissedStatus *status);

DescriptionThis operation obtains the DDS_RequestedDeadlineMissedStatus struct of theDDS_DataReader.

Parametersin DDS_DataReader _this - the DDS_DataReader object on which the

operation is operated.inout DDS_RequestedDeadlineMissedStatus *status - the contents of

t he DDS_RequestedDeadlineMissedStatus s t r u c t o f t h eDDS_DataReader will be copied into the location specified by status.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:DDS_RETCODE_OK , DDS_RETCODE_ERROR , DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

442API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Detailed DescriptionThis operation obtains the DDS_RequestedDeadlineMissedStatus struct of theDDS_DataReader. This struct contains the information whether the deadline thatthe DDS_DataReader was expecting through its DDS_DeadlineQosPolicy wasnot respected for a specific instance.The DDS_RequestedDeadlineMissedStatus can also be monitored using aDDS_DataReaderListener or by using the associated DDS_StatusCondition.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the current DDS_RequestedDeadlineMissedStatus of

this DDS_DataReader has successfully been copied into the specified statusparameter.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_DataReader has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

3.5.2.17 DDS_DataReader_get_requested_incompatible_qos_status

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReader_get_requested_incompatible_qos_status (DDS_DataReader _this, DDS_RequestedIncompatibleQosStatus *status);

DescriptionThis operation obtains the DDS_RequestedIncompatibleQosStatus struct ofthe DDS_DataReader.

Parametersin DDS_DataReader _this - the DDS_DataReader object on which the

operation is operated.inout DDS_RequestedIncompatibleQosStatus *status - the contents of

t he DDS_RequestedIncompatibleQosStatus s t r u c t o f t h eDDS_DataReader will be copied into the location specified by status.

443API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:DDS_RETCODE_OK , DDS_RETCODE_ERROR , DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation obtains the DDS_RequestedIncompatibleQosStatus struct ofthe DDS_DataReader. This struct contains the information whether a QosPolicysetting was incompatible with the offered QosPolicy setting.The Request/Offering mechanism is applicable between the DDS_DataWriter andthe DDS_DataReader. If the QosPolicy settings between DDS_DataWriter andDDS_DataReader are inconsistent, no communication between them isestablished. In addition the DDS_DataWriter will be informed via aDDS_REQUESTED_INCOMPATIBLE_QOS status change and the DDS_DataReaderwill be informed via an DDS_OFFERED_INCOMPATIBLE_QOS status change.The DDS_RequestedIncompatibleQosStatus can also be monitored using aDDS_DataReaderListener or by using the associated DDS_StatusCondition.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the current DDS_RequestedIncompatibleQosStatus of

this DDS_DataReader has successfully been copied into the specified statusparameter.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_DataReader has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

3.5.2.18 DDS_DataReader_get_sample_lost_status

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReader_get_sample_lost_status (DDS_DataReader _this, DDS_SampleLostStatus *status);

444API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

DescriptionThis opera t ion ob ta ins the DDS_SampleLostStatus s t ruc t o f theDDS_DataReader.

Parametersin DDS_DataReader _this - the DDS_DataReader object on which the

operation is operated.inout DDS_SampleLostStatus *status - t he con ten t s o f t he

DDS_SampleLostStatus struct of the DDS_DataReader will be copied intothe location specified by status.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:DDS_RETCODE_OK , DDS_RETCODE_ERROR , DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis opera t ion ob ta ins the DDS_SampleLostStatus s t ruc t o f theDDS_DataReader. This struct contains the information whether a sample havebeen lost. This only applies when the DDS_ReliabilityQosPolicy is set toDDS_RELIABLE . I f t h e DDS_ReliabilityQosPolicy i s s e t t oDDS_BEST_EFFORT the Data Distribution Service will not report the loss ofsamples.The DDS_SampleLostStatus c a n a l s o b e m o n i t o r e d u s i n g aDDS_DataReaderListener or by using the associated DDS_StatusCondition.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the current DDS_SampleLostStatus of thisDDS_DataReader has successfully been copied into the specified statusparameter.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_DataReader has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

445API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

3.5.2.19 DDS_DataReader_get_sample_rejected_status

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReader_get_sample_rejected_status (DDS_DataReader _this, DDS_SampleRejectedStatus *status);

Detailed DescriptionThis operation obtains the DDS_SampleRejectedStatus struct of theDDS_DataReader.

Parametersin DDS_DataReader _this - the DDS_DataReader object on which the

operation is operated.inout DDS_SampleRejectedStatus *status - the contents of the

DDS_SampleRejectedStatus struct of the DDS_DataReader will be copiedinto the location specified by status.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:DDS_RETCODE_OK , DDS_RETCODE_ERROR , DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation obtains the DDS_SampleRejectedStatus struct of theDDS_DataReader. This struct contains the information whether a received samplehas been rejected. Samples may be rejected by the DDS_DataReader when it runsout of resource_limits to store incoming samples. Ususally this means that oldsamples need to be ‘consumed’ (for example by ‘taking’ them instead of ‘reading’them) to make room for newly incoming samples.The DDS_SampleRejectedStatus can a l so be moni tored us ing aDDS_DataReaderListener or by using the associated DDS_StatusCondition.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the current DDS_SampleRejectedStatus of thisDDS_DataReader has successfully been copied into the specified statusparameter.

446API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_DataReader has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

3.5.2.20 DDS_DataReader_get_status_changes (inherited)This operation is inherited and therefore not described here. See the classDDS_Entity for further explanation.

Synopsis#include <dds_dcps.h>DDS_StatusMask DDS_DataReader_get_status_changes (DDS_DataReader _this);

3.5.2.21 DDS_DataReader_get_statuscondition (inherited)This operation is inherited and therefore not described here. See the classDDS_Entity for further explanation.

Synopsis#include <dds_dcps.h>DDS_StatusCondition DDS_DataReader_get_statuscondition (DDS_DataReader _this);

3.5.2.22 DDS_DataReader_get_subscriber

Synopsis#include <dds_dcps.h>DDS_Subscriber DDS_DataReader_get_subscriber (DDS_DataReader _this);

DescriptionThis operation returns the DDS_Subscriber to which the DDS_DataReaderbelongs.

Parametersin DDS_DataReader _this - the DDS_DataReader object on which the

operation is operated.

447

API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Return ValueDDS_Subscriber - Return value is a pointer to the DDS_Subscriber to which

the DDS_DataReader belongs.

Detailed DescriptionThis operation returns the DDS_Subscriber to which the DDS_DataReaderbelongs, thus the DDS_Subscriber that has created the DDS_DataReader. If theDDS_DataReader is already deleted, the DDS_OBJECT_NIL pointer is returned.

3.5.2.23 DDS_DataReader_get_subscription_matched_status

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReader_get_subscription_matched_status (DDS_DataReader _this, DDS_SubscriptionMatchedStatus *status);

DescriptionThis operation obtains the DDS_SubscriptionMatchedStatus struct of theDDS_DataReader.

Parametersin DDS_DataReader _this - the DDS_DataReader object on which the

operation is operated.inout DDS_SubscriptionMatchedStatus *status - the contents of the

DDS_SubscriptionMatchedStatus struct of the DDS_DataReader will becopied into the location specified by status.

Return ValueDDS_ReturnCode_t - Possible re turn codes of the operat ion are:DDS_RETCODE_OK , DDS_RETCODE_ERROR , DDS_RETCODE_ILLEGAL_OPERATION, RETCODE_UNSUPPORTED, DDS_RETCODE_ALREADY_DELETED orDDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation obtains the DDS_SubscriptionMatchedStatus struct of theDDS_DataReader. This struct contains the information whether a new match hasbeen discovered for the current subscription, or whether an existing match hasceased to exist.

448API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

This means that the status represents that either a DataWriter object has beendiscovered by the DDS_DataReader with the same Topic and a compatible Qos, orthat a previously-discovered DataWriter has ceased to be matched to the currentDDS_DataReader. A DataWriter may cease to match when it gets deleted, when itchanges its Qos to a value that is incompatible with the current DDS_DataReaderor when either the DDS_DataReader or the DataWriter has chosen to put itsmatching counterpart on its ignore-list using the DDS_DomainParticipant_ignore_publication or DDS_DomainParticipant_ignore_subscriptionoperations.The operation may fail if the infrastructure does not hold the information necessaryto fill in the DDS_SubscriptionMatchedStatus. This is the case whenOpenSplice is configured not to maintain discovery information in the NetworkingS e r v i c e . ( S e e t h e d e s c r i p t i o n f o r t h e NetworkingService/Discovery/enabled property in the Deployment Manual for more informationa b o u t t h i s s u b j e c t . ) I n t h i s c a s e t h e o p e ra t i o n w i l l r e t u r nDDS_RETCODE_UNSUPPORTED.The DDS_SubscriptionMatchedStatus can also be monitored using aDDS_DataReaderListener or by using the associated DDS_StatusCondition.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the current DDS_SubscriptionMatchedStatus of thisDDS_DataReader has successfully been copied into the specified statusparameter.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_UNSUPPORTED - OpenSplice is configured not to maintain the

information about “associated” publications.• DDS_RETCODE_ALREADY_DELETED - the DDS_DataReader has already been

deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

3.5.2.24 DDS_DataReader_get_topicdescription

Synopsis#include <dds_dcps.h>DDS_TopicDescription DDS_DataReader_get_topicdescription

449API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

(DDS_DataReader _this);

DescriptionThis operation returns the DDS_TopicDescription which is associated with theDDS_DataReader.

Parametersin DDS_DataReader _this - the DDS_DataReader object on which the

operation is operated.

Return ValueDDS_TopicDescription - a pointer to the DDS_TopicDescription which is

associated with the DDS_DataReader.

Detailed DescriptionThis operation returns the DDS_TopicDescription which is associated with theDDS_DataReader, thus the DDS_TopicDescription with which theDDS_DataReader is created. If the DDS_DataReader is already deleted, theDDS_OBJECT_NIL pointer is returned.

3.5.2.25 DDS_DataReader_lookup_instance (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReader class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataReader class.

Synopsis#include <dds_dcps.h>DDS_InstanceHandle_t DDS_DataReader_lookup_instance (DDS_DataReader _this,

<data> *instance_data);

3.5.2.26 DDS_DataReader_read (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReader class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataReader class.

Synopsis#include <dds_dcps.h>

450API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

DDS_ReturnCode_tDDS_DataReader_read

(DDS_DataReader _this,DDS_sequence_<data> *data_values,

DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

3.5.2.27 DDS_DataReader_read_instance (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReader class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataReader class.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t

DDS_DataReader_read_instance (DDS_DataReader _this,

DDS_sequence_<data> *data_values, DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

3.5.2.28 DDS_DataReader_read_next_instance (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReader class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataReader class.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t

DDS_DataReader_read_next_instance (DDS_DataReader _this,

DDS_sequence_<data> *data_values,DDS_SampleInfoSeq *info_seq,const DDS_long max_samples,const DDS_InstanceHandle_t a_handle,

451API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

const DDS_SampleStateMask sample_states,const DDS_ViewStateMask view_states,const DDS_InstanceStateMask instance_states);

3.5.2.29 DDS_DataReader_read_next_instance_w_condition (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReader class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataReader class.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t

DDS_DataReader_read_next_instance_w_condition (DDS_DataReader _this,

DDS_sequence_<data> *data_values,DDS_SampleInfoSeq *info_seq,const DDS_long max_samples,const DDS_InstanceHandle_t a_handle,const DDS_ReadCondition a_condition);

3.5.2.30 DDS_DataReader_read_next_sample (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReader class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataReader class.

Synopsis#include <dds_dcps.h>

DDS_ReturnCode_t DDS_DataReader_read_next_sample

(DDS_DataReader _this, <data> *data_values, DDS_SampleInfo *sample_info);

NOTE: This operation is not yet implemented. It is scheduled for a future release.

3.5.2.31 DDS_DataReader_read_w_condition (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReader class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataReader class.

452API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Synopsis#include <dds_dcps.h>

DDS_ReturnCode_t DDS_DataReader_read_w_condition

(DDS_DataReader _this, DDS_sequence_<data> *data_values, DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_ReadCondition a_condition);

3.5.2.32 DDS_DataReader_return_loan (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReader class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataReader class.

Synopsis#include <dds_dcps.h>

DDS_ReturnCode_t DDS_DataReader_return_loan

(DDS_DataReader _this, DDS_sequence_<data> *data_values, DDS_SampleInfoSeq *info_seq);

3.5.2.33 DDS_DataReader_set_default_datareaderview_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReader_set_default_datareaderview_qos (DDS_DataReader _this, DDS_DataReaderViewQos* qos);

DescriptionThi s ope ra t ion se t s t he de fau l t DDS_DataReaderViewQos o f t heDDS_DataReader.

Parametersin DDS_DataReader _this - the DDS_DataReader object on which the

operation is operated.in const DDS_DataReaderViewQos* qos - the DDS_DataReaderViewQos

struct which contains the default QosPolicy settings for newly-createdDDS_DataReaderView objects.

453API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Return ValueDDS_ReturnCode_t - Possible return codes of the operation are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_BAD_PARAMETER,DDS_RETCODE_OUT_OF_RESOURCES.

Detailed Description

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the new default DataReaderViewQos is set.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_BAD_PARAMETER - the DataReaderViewQos parameter is

invalid.• DDS_RETCODE_OUT_OF_RESOURCES - the data distribution service ran out of

resources to complete this operation.

3.5.2.34 DDS_DataReader_set_listener

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReader_set_listener (DDS_DataReader _this, const struct DDS_DataReaderListener *a_listener, const DDS_StatusMask mask);

DescriptionThis operation attaches a DDS_DataReaderListener to the DDS_DataReader.

Parametersin DDS_DataReader _this - the DDS_DataReader object on which the

operation is operated.in const struct DDS_DataReaderListener *a_listener - a pointer to

the DDS_DataReaderListener instance, which will be attached to theDDS_DataReader.

in const DDS_StatusMask mask - a bit-mask in which each bit enables theinvocation of the DDS_DataReaderListener for a certain status.

454API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_UNSUPPORTED , DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation attaches a DDS_DataReaderListener to the DDS_DataReader.Only one DDS_DataReaderListener can be attached to each DDS_DataReader.If a DDS_DataReaderListener was already attached, the operation will replace itwith the new one. When a_listener is the DDS_OBJECT_NIL pointer, itrepresents a listener that is treated as a NOOP1 for all statuses activated in thebitmask.

Communication StatusFor each communication status, the StatusChangedFlag flag is initially set toFALSE. It becomes TRUE whenever that communication status changes. For eachcommun ica t i on s t a t u s a c t i va t ed i n t he mask , t h e a s soc i a t e dDDS_DataReaderListener operation is invoked and the communication status isreset to FALSE, as the listener implicitly accesses the status which is passed as aparameter to that operation. The status is reset prior to calling the listener, so if theapplication calls the get_<status_name>_status from inside the listener it willsee the status already reset. An exception to this rule is the DDS_OBJECT_NILlistener, which does not reset the communication statuses for which it is invoked.The following statuses are applicable to the DDS_DataReaderListener:

DDS_REQUESTED_DEADLINE_MISSED_STATUSDDS_REQUESTED_INCOMPATIBLE_QOS_STATUSDDS_SAMPLE_LOST_STATUSDDS_SAMPLE_REJECTED_STATUSDDS_DATA_AVAILABLE_STATUSDDS_LIVELINESS_CHANGED_STATUSDDS_SUBSCRIPTION_MATCHED_STATUS.

Be aware that the DDS_SUBSCRIPTION_MATCHED_STATUS is not applicable whenthe infrastructure does not have the information available to determine connectivity.This is the case when OpenSplice is configured not to maintain discoveryinformation in the Networking Service. (See also the description of theNetworkService/Discovery[@enabled] attribute in section 4.4.1.6.1on page 244 of the Deployment Guide.) In this case the operation will returnDDS_RETCODE_UNSUPPORTED.

1. Short for No-Operation, an instruction that peforms nothing at all.

455

API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Status bits are declared as a constant and can be used by the application in an ORoperation to create a tailored mask. The special constant DDS_STATUS_MASK_NONEcan be used to indicate that the created entity should not respond to any of itsavailable statuses. The DDS will therefore attempt to propagate these statuses to itsfactory. The special constant STATUS_MASK_ANY_V1_2 can be used to select allapplicable statuses specified in the “Data Distribution Service for Real-timeSystems Version 1.2” specification.

Status PropagationIn case a communica t ion s ta tus i s not ac t iva ted in the mask o f theDDS_DataReaderListener, the DDS_SubscriberListener of the containingDDS_Subscriber is invoked (if attached and activated for the status that occurred).T h i s a l l o w s t h e a p p l i c a t i o n to s e t a d e f a u l t b e h a v i o u r i n t h eDDS_SubscriberListener of the containing DDS_Subscriber and aDDS_DataReader specific behaviour when needed. In case the communicationstatus is not activated in the mask of the DDS_SubscriberListener as well, thec o m m u n i c a t i o n s t a t u s w i l l b e p r o p a g a t e d t o t h eDDS_DomainParticipantListener o f t h e c o n t a i n i n gDDS_DomainParticipant. In case the DDS_DomainParticipantListener isalso not attached or the communication status is not activated in its mask, theapplication is not notified of the change.The s t a t u se s DDS_DATA_ON_READERS_STATUS a n d DDS_DATA_AVAILABLE_STATUS are “Read Communication Statuses” and are an exception toall other plain communication statuses: they have no corresponding status structurethat can be obtained with a get_<status_name>_status operation and they aremutually exclusive. When new information becomes available to a DataReader, theData Distribution Service will f irst look in an attached and activatedDDS_SubscriberListener or DDS_DomainParticipantListener (in thato r d e r ) f o r t h e DDS_DATA_ON_READERS_STATUS . I n c a s e t h eDDS_DATA_ON_READERS_STATUS can not be handled, the Data DistributionService will look in an attached and activated DDS_DataReaderListener,DDS_SubscriberListener or DDS_DomainParticipantListener for theDDS_DATA_AVAILABLE_STATUS (in that order).

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the DDS_DataReaderListener is attached.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.

456API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

• DDS_RETCODE_UNSUPPORTED - a status was selected that cannot be supportedbecause the infrastructure does not maintain the required connectivityinformation.

• DDS_RETCODE_ALREADY_DELETED - the DDS_DataReader has already beendeleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

3.5.2.35 DDS_DataReader_set_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReader_set_qos (DDS_DataReader _this, const DDS_DataReaderQos *qos);

DescriptionThis operation replaces the exist ing set of QosPolicy set t ings for aDDS_DataReader.

Parametersin DDS_DataReader _this - the DDS_DataReader object on which the

operation is operated.in const DDS_DataReaderQos *qos - the new set of QosPolicy settings for

the DDS_DataReader.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_UNSUPPORTED, DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES , DDS_RETCODE_IMMUTABLE_POLICY o rDDS_RETCODE_INCONSISTENT_POLICY.

Detailed DescriptionThis operation replaces the exist ing set of QosPolicy set t ings for aDDS_DataReader. The parameter qos contains the QosPolicy settings which ischecked for self-consistency and mutability. When the application tries to change aQosPolicy setting for an enabled DDS_DataReader, which can only be set beforethe DDS_DataReader i s e n a b l e d , t h e o p e r a t i o n w i l l f a i l a n d aDDS_RETCODE_IMMUTABLE_POLICY is returned. In other words, the application

457API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

must provide the presently set QosPolicy settings in case of the immutableQosPolicy settings. Only the mutable QosPolicy settings can be changed. Whenqos contains conflicting QosPolicy settings (not self-consistent), the operationwill fail and a DDS_RETCODE_INCONSISTENT_POLICY is returned.The set of QosPolicy settings specified by the qos parameter are applied on top ofthe existing QoS, replacing the values of any policies previously set (provided, theoperation returned DDS_RETCODE_OK).

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the new DDS_DataReaderQos is set.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the parameter qos is not a validDDS_DataReaderQos. It contains a QosPolicy setting with an invalidDDS_Duration_t value, an enum value that is outside its legal boundaries or asequence that has inconsistent memory settings.

• DDS_RETCODE_UNSUPPORTED - one or more of the selected QosPolicy valuesare currently not supported by OpenSplice.

• DDS_RETCODE_ALREADY_DELETED - the DDS_DataReader has already beendeleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_IMMUTABLE_POLICY - the parameter qos contains animmutable QosPolicy setting with a different value than set during enabling ofthe DDS_DataReader.

• DDS_RETCODE_INCONSISTENT_POLICY - the parameter qos containsconflicting QosPolicy settings, e.g. a history depth that is higher than thespecified resource limits.

3.5.2.36 DDS_DataReader_take (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReader class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataReader class.

458API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Synopsis#include <dds_dcps.h>

DDS_ReturnCode_t DDS_DataReader_take

(DDS_DataReader _this, DDS_sequence_<data> *data_values, DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

3.5.2.37 DDS_DataReader_take_instance (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReader class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataReader class.

Synopsis#include <dds_dcps.h>

DDS_ReturnCode_t DDS_DataReader_take_instance

(DDS_DataReader _this, DDS_sequence_<data> *data_values, DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

3.5.2.38 DDS_DataReader_take_next_instance (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReader class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataReader class.

Synopsis#include <dds_dcps.h>

DDS_ReturnCode_t DDS_DataReader_take_next_instance

(DDS_DataReader _this, DDS_sequence_<data> *data_values, DDS_SampleInfoSeq *info_seq,

459API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

3.5.2.39 DDS_DataReader_take_next_instance_w_condition (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReader class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataReader class.

Synopsis#include <dds_dcps.h>

DDS_ReturnCode_t DDS_DataReader_take_next_instance_w_condition

(DDS_DataReader _this, DDS_sequence_<data> *data_values, DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_ReadCondition a_condition);

3.5.2.40 DDS_DataReader_take_next_sample (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReader class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataReader class.

Synopsis#include <dds_dcps.h>

DDS_ReturnCode_t DDS_DataReader_take_next_sample

(DDS_DataReader _this, <data> *data_values, DDS_SampleInfo *sample_info);

NOTE: This operation is not yet implemented. It is scheduled for a future release.

460API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

3.5.2.41 DDS_DataReader_take_w_condition (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReader class. Therefore, to use this operation, thedata type specific implementation of this operation in its respective derived classmust be used. For further explanation see the description for the fictional data typeFoo (defined in the module SPACE) derived SPACE_FooDataReader class.

Synopsis#include <dds_dcps.h>

DDS_ReturnCode_t DDS_DataReader_take_w_condition

(DDS_DataReader _this, DDS_sequence_<data> *data_values, DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_ReadCondition a_condition);

3.5.2.42 DDS_DataReader_wait_for_historical_data

Synopsis#include <dds_dcps.h>

DDS_ReturnCode_t DDS_DataReader_wait_for_historical_data

(DDS_DataReader _this, const DDS_Duration_t *max_wait);

DescriptionThis operation will block the application thread until all “historical” data isreceived.

Parametersin DDS_DataReader _this - the DDS_DataReader object on which the

operation is operated.in const DDS_Duration_t *max_wait - the maximum duration to block for

the DDS_DataReader_wait_for_historical_data, after which theapp l i c a t i on t h r e ad i s unb locke d . The spec i a l c ons t a n tDDS_DURATION_INFINITE can be used when the maximum waiting time doesnot need to be bounded.

461API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Return ValueDDS_ReturnCode_t - Possible return codes of the operation are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_ALREADY_DELETED , DDS_RETCODE_OUT_OF_RESOURCES , DDS_RETCODE_NOT_ENABLED,DDS_RETCODE_TIMEOUT or DDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionThis operation behaves differently for DDS_DataReader objects which have anon-DDS_VOLATILE_DURABILITY_QOS DDS_DurabilityQosPolicy and forDDS_DataReader objects which have a DDS_VOLATILE_DURABILITY_QOSDDS_DurabilityQosPolicy.As soon as an application enables a non-DDS_VOLATILE_DURABILITY_QOSDDS_DataReader it will start receiving both “historical” data, i.e. the data that waswritten prior to the time the DDS_DataReader joined the domain, as well as anynew data written by the DDS_DataWriter objects. There are situations where theapplication logic may require the application to wait until all “historical” data isr e c e i v e d . T h i s i s t h e p u r p o s e o f t h eDDS_DataReader_wait_for_historical_data operation.As soon as an application enables a DDS_VOLATILE_DURABILITY_QOSDataReader it will not start receiving “historical” data but only new data writtenby t he DDS_DataWriter ob j e c t s . By ca l l i ngDDS_DataReader_wait_for_historical_data the DDS_DataReaderexplicitly requests the Data Distribution Service to start receiving also the“historical” data and to wait until either all “historical” data is received, or theduration specified by the max_wait parameter has elapsed, whichever happensfirst.

Thread blockingThe operation DDS_DataReader_wait_for_historical_data blocks thecalling thread until either all “historical” data is received, or the duration specifiedby the max_wait parameter elapses, whichever happens first. A return value ofDDS_RETCODE_OK indicates that all the “historical” data was received; a returnvalue of DDS_RETCODE_TIMEOUT indicates that max_wait elapsed before all thedata was received.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the “historical” data is received.• DDS_RETCODE_ERROR - an internal error has occurred.

462API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on aninappropriate object.

• DDS_RETCODE_ALREADY_DELETED - the DDS_DataReader has already beendeleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_NOT_ENABLED - the DDS_DataReader is not enabled.• DDS_RETCODE_TIMEOUT - not all data is received before max_wait elapsed.• DDS_RETCODE_PRECONDITION_NOT_MET - can happen when requesting

conditional alignment on non-volatile readers or a historical data request isalready in progress or complete.

3.5.2.43 DDS_DataReader_wait_for_historical_data_w_condition

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReader_wait_for_historical_data_w_condition (DDS_DataReader _this const DDS_string filter_expression, const DDS_StringSeq* filter_parameters, const DDS_Time_t* min_source_timestamp, const DDS_Time_t* max_source_timestamp const DDS_ResourceLimitsQosPolicy* resource_limits, const DDS_Duration_t* max_wait)

DescriptionThis operation will block the application thread until all historical data that matchesthe supplied conditions is received.NOTE: This operation only makes sense when the receiving node has configured itsdurability service as an On_Request alignee. (See also the description of theOpenSplice/DurabilityService/NameSpaces/Policy[@alignee]attribute in the Deployment Guide.) Otherwise the Durability Service will notdistinguish between separate reader requests and still inject the full historical dataset in each reader.Additionally, when creating the DataReader, the DurabilityQos.kind of theDataReaderQos needs to be set to VOLATILE, to ensure that historical data thatpotentially is available already at creation time is not immediately delivered to theDataReader at that time.

463API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Parametersin DDS_DataReader _this - the DDS_DataReader object on which the

operation is operated.in const DDS_string* filter_expression - the SQL expression (subset of

SQL), which defines the filtering criteria (NULL when no SQL filtering isneeded).

in const DDS_StringSeq* filter_parameters – sequence of strings withthe parameter values used in the SQL expression (i.e., the number of %n tokensin the expression). The number of values in expression_parameters mustbe equal to or greater than the highest referenced %n token in thefilter_expression (e.g. if %1 and %8 are used as parameters in thefilter_expression, the expression_parameters should contain at leastn + 1 = 9 values).

in const DDS_Time_t* min_source_timestamp - Filter out all datapublished before this time. The special constant DDS_TIMESTAMP_INVALIDc a n b e u s e d w h e n n o m in i m u m f i l t e r i s n e e d e d . Th e v a l u e o fmin_source_timestamp.sec must be less than 0x7fffffff otherwise itwill be recognized as TIMESTAMP_INVALID_SEC.

in const DDS_Time_t* max_source_timestamp - Filter out all datapublished after this time. The special constant DDS_TIMESTAMP_INVALID canb e u s e d w h e n n o m a x i m u m f i l t e r i s ne ede d . The va lue o fmax_source_timestamp.sec must be less than 0x7fffffff otherwise itwill be recognized as TIMESTAMP_INVALID_SEC.

in const DDS_ResourceLimitsQosPolicy* resource_limits - Specifieslimits on the maximum amount of historical data that may be received.

in const DDS_Duration_t* max_wait - The maximum duration theapplication thread is blocked during this operation.

Return ValueDDS_ReturnCode_t - Possible return codes of the operation are:

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_BAD_PARAMETER,DDS_RETCODE_PRECONDITION_NOT_MET,DDS_RETCODE_ALREADY_DELETED , DDS_RETCODE_NOT_ENABLED,DDS_RETCODE_TIMEOUT.

464API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Detailed DescriptionT h i s o p e r a t i o n i s s i m i l a r t o t h eDDS_DataReader_wait_for_historical_data operation, but instead ofinserting all historical data into the DataReader, only data that matches theconditions expressed by the parameters to this opération is inserted. For moreinformation about historical data please refer to section 3.5.2.42 on page 461.By using filter_expression and filter_parameters, data can be selectedor discarded based on content. The filter_expression must adhere to SQLsyntax of the WHERE clause as described in Appendix H, DCPS Queries and Filters.Constraints on the age of data can be set by using the min_source_timestampand max_source_timestamp parameters. Only data published within thistimeframe will be selected. Note that DDS_TIMESTAMP_INVALID is also acceptedas a lower or upper timeframe limit. The amount of selected data can be furtherreduced by the resource_limits parameter. This QosPolicy allows to set a limiton the number of samples, instances and samples per instance that are to bereceived.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the historical data is received.• DDS_RETCODE_ERROR - an internal error occurred.• DDS_RETCODE_BAD_PARAMETER - any of the parameters is invalid, includingresource_limits that do not meet constraints set on the DataReader.

• RETCODE_PRECONDITION_NOT_MET - No Durability service is available, or canhappen when requesting conditional alignment on non-volatile readers or ahistorical data request is already in progress or complete.

• DDS_RETCODE_ALREADY_DELETED - the DataReader is already deleted.• DDS_RETCODE_NOT_ENABLED - the DataReader is not enabled.• DDS_RETCODE_TIMEOUT - not all data is received before max_wait elapsed.

3.5.2.44 Class SPACE_FooDataReaderThe pre-processor generates from IDL type descriptions the application<NameSpace>_<type>DataReader classes. For each application data type that isused as DDS_Topic data type, a typed class <NameSpace>_<type>DataReaderis derived from the DDS_DataReader class. In this paragraph, the classSPACE_FooDataReader descr ibes the opera t ions of these der ived<NameSpace>_<type>DataReader classes as an example for the fictionalapplication type Foo (defined in the module SPACE).

465API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

For instance, for an application, the definitions are located in the Space.idl file.The pre-processor will generate a Space.h include file.

State masksA SPACE_FooDataReader refers to exactly one DDS_TopicDescription (eithera DDS_Topic, a DDS_ContentFilteredTopic or a DDS_MultiTopic) thatidentifies the data to be read. Therefore it refers to exactly one data type. TheDDS_Topic must exist prior to the SPACE_FooDataReader creation. TheSPACE_FooDataReader may give access to several instances of the data type,wh ich a r e d i s t i ngu i she d f rom eac h o the r by t he i r key. T h eSPACE_FooDataReader is attached to exactly one DDS_Subscriber which actsas a factory for it. The interface description of this class is as follows:

/* * interface SPACE_FooDataReader *//* * inherited from class DDS_Entity *//* DDS_StatusCondition * SPACE_FooDataReader_get_statuscondition * (SPACE_FooDataReader _this); *//* DDS_StatusMask * SPACE_FooDataReader_get_status_changes * (SPACE_FooDataReader _this); *//* DDS_ReturnCode_t * SPACE_FooDataReader_enable * (SPACE_FooDataReader _this); *//* * inherited from class DDS_DataReader *//* DDS_ReadCondition * SPACE_FooDataReader_create_readcondition * (SPACE_FooDataReader _this, * const DDS_SampleStateMask sample_states, * const DDS_ViewStateMask view_states, * const DDS_InstanceStateMask instance_states); */

/* DDS_QueryCondition * SPACE_FooDataReader_create_querycondition * (SPACE_FooDataReader _this, * const DDS_SampleStateMask sample_states, * const DDS_ViewStateMask view_states,

466API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

* const DDS_InstanceStateMask instance_states, * const DDS_char *query_expression, * const DDS_StringSeq *query_parameters); */

/* DDS_ReturnCode_t * SPACE_FooDataReader_delete_readcondition * (SPACE_FooDataReader _this, * const DDS_ReadCondition a_condition); */

/* DDS_ReturnCode_t * SPACE_FooDataReader_delete_contained_entities * (SPACE_FooDataReader _this); */

/* DDS_ReturnCode_t * SPACE_FooDataReader_set_qos * (SPACE_FooDataReader _this, * const DDS_DataReaderQos *qos); */

/* DDS_ReturnCode_t * SPACE_FooDataReader_get_qos * (SPACE_FooDataReader _this, * SPACE_FooDataReaderQos *qos); */

/* DDS_ReturnCode_t * SPACE_FooDataReader_set_listener * (SPACE_FooDataReader _this, * const struct DDS_DataReaderListener *a_listener, * const DDS_StatusMask mask); */

/* struct SPACE_FooDataReaderListener * SPACE_FooDataReader_get_listener * (SPACE_FooDataReader _this); */

/* DDS_TopicDescription * SPACE_FooDataReader_get_topicdescription * (SPACE_FooDataReader _this); */

/* DDS_Subscriber * SPACE_FooDataReader_get_subscriber * (SPACE_FooDataReader _this); */

467API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

/* DDS_ReturnCode_t * SPACE_FooDataReader_get_sample_rejected_status * (SPACE_FooDataReader _this, * DDS_SampleRejectedStatus *status); */

/* DDS_ReturnCode_t * SPACE_FooDataReader_get_liveliness_changed_status * (SPACE_FooDataReader _this, * DDS_LivelinessChangedStatus *status); */

/* DDS_ReturnCode_t * SPACE_FooDataReader_get_requested_deadline_missed_status * (SPACE_FooDataReader _this, * DDS_RequestedDeadlineMissedStatus *status); */

/* DDS_ReturnCode_t * SPACE_FooDataReader_get_requested_incompatible_qos_status * (SPACE_FooDataReader _this, * DDS_RequestedIncompatibleQosStatus *status); */

/* DDS_ReturnCode_t * SPACE_FooDataReader_get_subscription_matched_status * (SPACE_FooDataReader _this, * DDS_SubscriptionMatchedStatus *status); */

/* DDS_ReturnCode_t * SPACE_FooDataReader_get_sample_lost_status * (SPACE_FooDataReader _this, * DDS_SampleLostStatus *status); */

/* DDS_ReturnCode_t * SPACE_FooDataReader_wait_for_historical_data * (SPACE_FooDataReader _this, * const DDS_Duration_t *max_wait); */

/* DDS_ReturnCode_t * SPACE_FooDataReader_get_matched_publications * (SPACE_FooDataReader _this, * DDS_InstanceHandleSeq *publication_handles); */

/* DDS_ReturnCode_t * SPACE_FooDataReader_get_matched_publication_data

468API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

* (SPACE_FooDataReader _this, * DDS_PublicationBuiltinTopicData *publication_data, * const DDS_InstanceHandle_t publication_handle); *//* * implemented API operations */

DDS_ReturnCode_t SPACE_FooDataReader_read (SPACE_FooDataReader _this, DDS_sequence_Foo *data_values, DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);DDS_ReturnCode_t SPACE_FooDataReader_take (SPACE_FooDataReader _this, DDS_sequence_Foo *data_values, DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);DDS_ReturnCode_t SPACE_FooDataReader_read_w_condition (SPACE_FooDataReader _this, DDS_sequence_Foo *data_values, DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_ReadCondition a_condition);DDS_ReturnCode_t SPACE_FooDataReader_take_w_condition (SPACE_FooDataReader _this, DDS_sequence_Foo *data_values, DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_ReadCondition a_condition);DDS_ReturnCode_t SPACE_FooDataReader_read_next_sample (SPACE_FooDataReader _this, Foo *data_values, DDS_SampleInfo *sample_info);DDS_ReturnCode_t SPACE_FooDataReader_take_next_sample (SPACE_FooDataReader _this, Foo *data_values, DDS_SampleInfo *sample_info);DDS_ReturnCode_t

469API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

SPACE_FooDataReader_read_instance (SPACE_FooDataReader _this, DDS_sequence_Foo *data_values, DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);DDS_ReturnCode_t SPACE_FooDataReader_take_instance (SPACE_FooDataReader _this, DDS_sequence_Foo *data_values, DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);DDS_ReturnCode_t SPACE_FooDataReader_read_next_instance (SPACE_FooDataReader _this, DDS_sequence_Foo *data_values, DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);DDS_ReturnCode_t SPACE_FooDataReader_take_next_instance (SPACE_FooDataReader _this, DDS_sequence_Foo *data_values, DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);DDS_ReturnCode_t SPACE_FooDataReader_read_next_instance_w_condition (SPACE_FooDataReader _this, DDS_sequence_Foo *data_values, DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_ReadCondition a_condition);DDS_ReturnCode_t SPACE_FooDataReader_take_next_instance_w_condition (SPACE_FooDataReader _this,

470API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

DDS_sequence_Foo *data_values, DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_ReadCondition a_condition);DDS_ReturnCode_t SPACE_FooDataReader_return_loan (SPACE_FooDataReader _this, DDS_sequence_Foo *data_values, DDS_SampleInfoSeq *info_seq);DDS_ReturnCode_t SPACE_FooDataReader_get_key_value (SPACE_FooDataReader _this, Foo *key_holder, const DDS_InstanceHandle_t handle);DDS_InstanceHandle_t SPACE_FooDataReader_lookup_instance (SPACE_FooDataReader _this, Foo *instance_data);

The next paragraphs describe the usage of all SPACE_FooDataReader operations.The inherited operations are listed but not fully described because they are notimplemented in this class. The full description of these operations is given in theclasses from which they are inherited.

3.5.2.45 SPACE_FooDataReader_create_querycondition (inherited)This operation is inherited and therefore not described here. See the classDDS_DataReader for further explanation.

Synopsis#include <Space.h>DDS_QueryCondition SPACE_FooDataReader_create_querycondition (SPACE_FooDataReader _this, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states, const DDS_char *query_expression, const DDS_StringSeq *query_parameters);

3.5.2.46 SPACE_FooDataReader_create_readcondition (inherited)This operation is inherited and therefore not described here. See the classDDS_DataReader for further explanation.

Synopsis#include <Space.h>DDS_ReadCondition

471API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

SPACE_FooDataReader_create_readcondition (SPACE_FooDataReader _this, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

3.5.2.47 SPACE_FooDataReader_delete_contained_entities (inherited)This operation is inherited and therefore not described here. See the classDDS_DataReader for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReader_delete_contained_entities (SPACE_FooDataReader _this);

3.5.2.48 SPACE_FooDataReader_delete_readcondition (inherited)This operation is inherited and therefore not described here. See the classDDS_DataReader for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReader_delete_readcondition (SPACE_FooDataReader _this, const DDS_ReadCondition a_condition);

3.5.2.49 SPACE_FooDataReader_enable (inherited)This operation is inherited and therefore not described here. See the classDDS_Entity for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReader_enable (SPACE_FooDataReader _this);

3.5.2.50 SPACE_FooDataReader_get_key_value

Synopsis#include <Space.h>

DDS_ReturnCode_tSPACE_FooDataReader_get_key_value

(SPACE_FooDataReader _this, Foo *key_holder, const DDS_InstanceHandle_t handle);

472API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

DescriptionThis operation retrieves the key value of a specific instance.

Parametersin SPACE_FooDataReader _this - the SPACE_FooDataReader object on

which the operation is operated.inout Foo *key_holder - the sample in which the key values are stored.in const DDS_InstanceHandle_t handle - the handle to the instance from

which to get the key value.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED or DDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionThis operat ion retr ieves the key value of the instance pointed to byinstance_handle. When the operation is called with an DDS_HANDLE_NILhand l e va lue a s an instance_handle , t h e ope ra t i on w i l l r e t u rnDDS_RETCODE_BAD_PARAMETER. The operation will only fill the fields that formthe key inside the key_holder instance. This means that the non-key fields are notapplicable and may contain garbage.The operation must only be called on registered instances. Otherwise the operationreturns the error DDS_RETCODE_PRECONDITION_NOT_MET.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the key_holder instance contains the key values of the

instance.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - handle is not a valid handle or key_holder

is not a valid pointer.• DDS_RETCODE_ALREADY_DELETED - the SPACE_FooDataReader has already

been deleted.

473API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_NOT_ENABLED - the SPACE_FooDataReader is not enabled.• DDS_RETCODE_PRECONDITION_NOT_MET - this instance is not registered.

3.5.2.51 SPACE_FooDataReader_get_listener (inherited)This operation is inherited and therefore not described here. See the classDDS_DataReader for further explanation.

Synopsis#include <Space.h>struct SPACE_FooDataReaderListener SPACE_FooDataReader_get_listener (SPACE_FooDataReader _this);

3.5.2.52 SPACE_FooDataReader_get_liveliness_changed_status (inherited)This operation is inherited and therefore not described here. See the classDDS_DataReader for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReader_get_liveliness_changed_status (SPACE_FooDataReader _this, DDS_LivelinessChangedStatus *status);

3.5.2.53 SPACE_FooDataReader_get_matched_publication_data (inherited)This operation is inherited and therefore not described here. See the classDDS_DataReader for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReader_get_matched_publication_data (SPACE_FooDataReader _this, DDS_PublicationBuiltinTopicData *publication_data, const DDS_InstanceHandle_t publication_handle);

3.5.2.54 SPACE_FooDataReader_get_matched_publications (inherited)This operation is inherited and therefore not described here. See the classDDS_DataReader for further explanation.

474API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReader_get_matched_publications (SPACE_FooDataReader _this, DDS_InstanceHandleSeq *publication_handles);

3.5.2.55 SPACE_FooDataReader_get_qos (inherited)This operation is inherited and therefore not described here. See the classDDS_DataReader for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReader_get_qos (SPACE_FooDataReader _this, DDS_DataReaderQos *qos);

3.5.2.56 SPACE_FooDataReader_get_requested_deadline_missed_status (inherited)

This operation is inherited and therefore not described here. See the classDDS_DataReader for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReader_get_requested_deadline_missed_status (SPACE_FooDataReader _this, DDS_RequestedDeadlineMissedStatus *status);

3.5.2.57 SPACE_FooDataReader_get_requested_incompatible_qos_status (inherited)

This operation is inherited and therefore not described here. See the classDDS_DataReader for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReader_get_requested_incompatible_qos_status (SPACE_FooDataReader _this, DDS_RequestedIncompatibleQosStatus *status);

475API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

3.5.2.58 SPACE_FooDataReader_get_sample_lost_status (inherited)This operation is inherited and therefore not described here. See the classDDS_DataReader for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReader_get_sample_lost_status (SPACE_FooDataReader _this, DDS_SampleLostStatus *status);

3.5.2.59 SPACE_FooDataReader_get_sample_rejected_status (inherited)This operation is inherited and therefore not described here. See the classDDS_DataReader for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReader_get_sample_rejected_status (SPACE_FooDataReader _this, DDS_SampleRejectedStatus *status);

3.5.2.60 SPACE_FooDataReader_get_status_changes (inherited)This operation is inherited and therefore not described here. See the classDDS_Entity for further explanation.

Synopsis#include <Space.h>DDS_StatusMask SPACE_FooDataReader_get_status_changes (SPACE_FooDataReader _this);

3.5.2.61 SPACE_FooDataReader_get_statuscondition (inherited)This operation is inherited and therefore not described here. See the classDDS_Entity for further explanation.

Synopsis#include <Space.h>DDS_StatusCondition SPACE_FooDataReader_get_statuscondition (SPACE_FooDataReader _this);

476API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

3.5.2.62 SPACE_FooDataReader_get_subscriber (inherited)This operation is inherited and therefore not described here. See the classDDS_DataReader for further explanation.

Synopsis#include <Space.h>DDS_Subscriber SPACE_FooDataReader_get_subscriber (SPACE_FooDataReader _this);

3.5.2.63 SPACE_FooDataReader_get_subscription_matched_status (inherited)This operation is inherited and therefore not described here. See the classDDS_DataReader for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReader_get_subscription_matched_status (SPACE_FooDataReader _this, DDS_SubscriptionMatchedStatus *status);

3.5.2.64 SPACE_FooDataReader_get_topicdescription (inherited)This operation is inherited and therefore not described here. See the classDDS_DataReader for further explanation.

Synopsis#include <Space.h>DDS_TopicDescription SPACE_FooDataReader_get_topicdescription (SPACE_FooDataReader _this);

3.5.2.65 SPACE_FooDataReader_lookup_instance

Synopsis#include <Space.h>DDS_InstanceHandle_t SPACE_FooDataReader_lookup_instance (SPACE_FooDataReader _this,

Foo *instance_data);

DescriptionThis operation returns the value of the instance handle which corresponds to theinstance_data.

477API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Parametersin SPACE_FooDataReader _this - the SPACE_FooDataReader object on

which the operation is operated.in Foo *instance_data - the instance for which the corresponding instance

handle needs to be looked up.

Return ValueDDS_InstanceHandle_t - Result value is the instance handle which corresponds

to the instance_data.

Detailed DescriptionThis operation returns the value of the instance handle which corresponds to theinstance_data. The instance handle can be used in read operations that operateon a specific instance. Note that DDS_DataReader instance handles are local, andare not interchangeable with DDS_DataWriter instance handles nor with instancehandles of an other DDS_DataReader. If the DDS_DataReader is already deleted,the handle value DDS_HANDLE_NIL is returned.

3.5.2.66 SPACE_FooDataReader_read

Synopsis#include <Space.h>

DDS_ReturnCode_t SPACE_FooDataReader_read

(SPACE_FooDataReader _this, DDS_sequence_Foo *data_values, DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

DescriptionThis operation reads a sequence of Foo samples from the SPACE_FooDataReader.

Parametersin SPACE_FooDataReader _this - the SPACE_FooDataReader object on

which the operation is operated.inout DDS_sequence_Foo *data_values - the returned sample data

sequence. data_values is also used as an input to control the behaviour of thisoperation.

478API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

inout DDS_SampleInfoSeq *info_seq - the returned DDS_SampleInfostructure sequence. info_seq is also used as an input to control the behaviourof this operation.

in const DDS_long max_samples - the maximum number of samples that isreturned.

in const DDS_SampleStateMask sample_states - a mask, which selectsonly those samples with the desired sample states.

in const DDS_ViewStateMask view_states - a mask, which selects onlythose samples with the desired view states.

in const DDS_InstanceStateMask instance_states - a mask, whichselects only those samples with the desired instance states.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED , DDS_RETCODE_PRECONDITION_NOT_MET o rDDS_RETCODE_NO_DATA.

Detailed DescriptionThis operation reads a sequence of Foo samples from the SPACE_FooDataReader.The data is returned by the parameters data_values and info_seq. The numberof samples that is returned is limited by the parameter max_samples. Thisoperation is part of the specialized class which is generated for the particularapplication data type (in this case type Foo) that is being read. If theSPACE_FooDataReader has no samples that meet the constraints, the return valueis DDS_RETCODE_NO_DATA.

State masksThe SPACE_FooDataReader_read operation depends on a selection of thesamples by using three masks:• sample_states is the mask, which selects only those samples with the desired

sample states DDS_READ_SAMPLE_STATE, DDS_NOT_READ_SAMPLE_STATE orboth

• view_states is the mask, which selects only those samples with the desiredview states DDS_NEW_VIEW_STATE, DDS_NOT_NEW_VIEW_STATE or both

479API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

• instance_states is the mask, which selects only those samples with thedesired instance states DDS_ALIVE_INSTANCE_STATE, DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE, DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE or a combination of these.

Destination OrderIn any case, the relative order between the samples of one instance is consistent withthe DDS_DestinationOrderQosPolicy of the DDS_Subscriber.W h e n t h e DDS_DestinationOrderQosPolicy kind i sDDS_BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS, the samplesbelonging to the same instances will appear in the relative order in which they werereceived (FIFO)W h e n t h e DDS_DestinationOrderQosPolicy kind i sDDS_BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS, the samples belongingto the same instances will appear in the relative order implied by thesource_timestamp.

Data sampleIn addition to the sample sequence (data_values), the operation also returns asequence of DDS_SampleInfo structures with the parameter info_seq. Theinfo_seq structures and data_values also determine the behaviour of thisoperation.

Resource controlThe initial (input) properties of the data_values and info_seq sequencesdetermine the precise behaviour of the SPACE_FooDataReader_read operation.The sequences are modelled as having three properties: the current-length(_length), the maximum length (_maximum), and whether or not the sequencecontainer owns the memory of the elements within (_release).The initial (input) values of the _length, _maximum, and _release properties forthe data_values and info_seq sequences govern the behaviour of theSPACE_FooDataReader_read operation as specified by the following rules:• The values of _length, _maximum, and _release for the two sequences must

be identical. Otherwise SPACE_FooDataReader_read returnsDDS_RETCODE_PRECONDITION_NOT_MET

• On successful output, the values of _length, _maximum, and _release are thesame for both sequences

• If the input _maximum==0, the data_values and info_seq sequences arefilled with elements that are “loaned” by the SPACE_FooDataReader. Onoutput, _release is FALSE, _length is set to the number of values returned,

480API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

and _maximum is set to a value verifying _maximum>=_length. In this case theapplication will need to “return the loan” to the Data Distribution Service usingthe SPACE_FooDataReader_return_loan operation

• If the input _maximum>0 and the input _release==FALSE, theSPACE_FooDataReader_read operation will fail and returnsDDS_RETCODE_PRECONDITION_NOT_MET. This avoids the potentialhard-to-detect memory leaks caused by an application forgetting to “return theloan”

• If input _maximum>0 and the input _release==TRUE, theSPACE_FooDataReader_read operation will copy the Foo samples andinfo_seq values into the elements already inside the sequences. On output,_release is TRUE, _length is set to the number of values copied, and_maximum will remain unchanged. The application can control where the copy isplaced and the application does not need to “return the loan”. The number ofsamples copied depends on the relative values of _maximum and max_samples: - If _maximum==DDS_LENGTH_UNLIMITED, at most _maximum values are

copied. The use of this variant lets the application limit the number of samplesreturned to what the sequence can accommodate;

- If max_samples<=_maximum, at most max_samples values are copied. Theuse of this variant lets the application limit the number of samples returned tofewer than what the sequence can accommodate;

- If max_samples>_maximum, the SPACE_FooDataReader_read operationwill fail and returns DDS_RETCODE_PRECONDITION_NOT_MET. This avoids thepotential confusion where the application expects to be able to access up tomax_samples, but that number can never be returned, even if they areavailable in the SPACE_FooDataReader, because the output sequence cannotaccommodate them.

Buffer LoanAs described above, upon return the data_values and info_seq sequences maycontain elements “loaned” from the Data Distribution Service. If this is the case, theapplication will need to use the SPACE_FooDataReader_return_loan operationto return the “loan” once it is no longer using the data in the sequence. Upon returnfrom SPACE_FooDataReader_return_loan, the sequence has _maximum==0and _release==FALSE.The application can determine whether it is necessary to “return the loan” or not,based on the state of the sequences, when the SPACE_FooDataReader_readoperation was called, or by accessing the “_release” property. However, in many

481API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

cases it may be simpler to always call SPACE_FooDataReader_return_loan, asthis operation is harmless (i.e. leaves all elements unchanged) if the sequence doesnot have a loan.To avoid potential memory leaks, it is not allowed to change the length of thedata_values and info_seq structures for which _release==FALSE.Furthermore, deleting a sequence for which _release==FALSE is considered to bean error except when the sequence is empty.

Data SequenceOn output, the sequence of data values and the sequence of DDS_SampleInfostructures are of the same length and are in an one-to-one correspondence. EachDDS_SampleInfo s t r u c tu r e s p r o v i d e s i n f o r m a t i o n , s u c h a s t h esource_timestamp, the sample_state, view_state, and instance_state,etc., about the matching sample.Some elements in the returned sequence may not have valid data: the valid_datafield in the DDS_SampleInfo indicates whether the corresponding data valuecontains any meaningful data. If not, the data value is just a ‘dummy’ sample forwhich only the keyfields have been assigned. It is used to accompany theDDS_SampleInfo that communicates a change in the instance_state of aninstance for which there is no ‘real’ sample available.For example, when an application always ‘takes’ all available samples of aparticular instance, there is no sample available to report the disposal of thatinstance. In such a case the DDS_DataReader will insert a dummy sample into thedata_values sequence to accompany the DDS_SampleInfo element in theinfo_seq sequence that communicates the disposal of the instance.The act of reading a sample sets its sample_state to DDS_READ_SAMPLE_STATE.If the sample belongs to the most recent generation of the instance, it also sets theview_state of the instance to DDS_NOT_NEW_VIEW_STATE. It does not affect theinstance_state of the instance.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - a sequence of data values is available.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - either or both of data_values or info_seq

is an invalid pointer.

482API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

• DDS_RETCODE_ALREADY_DELETED - the SPACE_FooDataReader has alreadybeen deleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_NOT_ENABLED - the SPACE_FooDataReader is not enabled.• DDS_RETCODE_PRECONDITION_NOT_MET - one of the following is true:

- the max_samples>_maximum and max_samples is notDDS_LENGTH_UNLIMITED.

- one or more values of _length, _maximum, and _release for the twosequences are not identical.

- the _maximum>0 and the _release==FALSE.• DDS_RETCODE_NO_DATA - no samples that meet the constraints are available.

3.5.2.67 SPACE_FooDataReader_read_instance

Synopsis#include <Space.h>

DDS_ReturnCode_t SPACE_FooDataReader_read_instance

(SPACE_FooDataReader _this, DDS_sequence_Foo *data_values, DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

DescriptionThis operation reads a sequence of Foo samples of a single instance from theSPACE_FooDataReader.

Parametersin SPACE_FooDataReader _this - the SPACE_FooDataReader object on

which the operation is operated.inout DDS_sequence_Foo *data_values - the returned sample data

sequence. data_values is also used as an input to control the behaviour of thisoperation.

inout DDS_SampleInfoSeq *info_seq - the returned DDS_SampleInfostructure sequence. info_seq is also used as an input to control the behaviourof this operation.

483API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

in const DDS_long max_samples - the maximum number of samples that isreturned.

in const DDS_InstanceHandle_t a_handle - the single instance, thesamples belong to.

in const DDS_SampleStateMask sample_states - a mask, which selectsonly those samples with the desired sample states.

in const DDS_ViewStateMask view_states - a mask, which selects onlythose samples with the desired view states.

in const DDS_InstanceStateMask instance_states - a mask, whichselects only those samples with the desired instance states.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED , DDS_RETCODE_PRECONDITION_NOT_MET o rDDS_RETCODE_NO_DATA.

Detailed DescriptionThis operation reads a sequence of Foo samples of a single instance from theSPACE_FooDataReader. T h e b e h a v i o u r i s i d e n t i c a l t oSPACE_FooDataReader_read except for that all samples returned belong to thesingle specified instance whose handle is a_handle. Upon successful return, thedata collection will contain samples all belonging to the same instance. The data isreturned by the parameters data_values and info_seq. The correspondingDDS_SampleInfo.instance_handle in info_seq will have the value ofa_handle. The DDS_DataReader will check that each sample belongs to thespecified instance (indicated by a_handle) otherwise it will not place the sample inthe returned collection.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - a sequence of data values is available.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - either or both of data_values or info_seq

is an invalid pointer or a_handle is not a valid handle.

484API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

• DDS_RETCODE_ALREADY_DELETED - the SPACE_FooDataReader has alreadybeen deleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_NOT_ENABLED - the SPACE_FooDataReader is not enabled.• DDS_RETCODE_PRECONDITION_NOT_MET - one of the following is true:

- the max_samples>_maximum and max_samples is notDDS_LENGTH_UNLIMITED.

- one or more values of _length, _maximum, and _release for the twosequences are not identical.

- the _maximum>0 and the _release==FALSE. - the handle ==DDS_HANDLE_NIL. - the handle has not been registered with this DataReader.

• DDS_RETCODE_NO_DATA - no samples that meet the constraints are available.

3.5.2.68 SPACE_FooDataReader_read_next_instance

Synopsis#include <Space.h>

DDS_ReturnCode_t SPACE_FooDataReader_read_next_instance

(SPACE_FooDataReader _this, DDS_sequence_Foo *data_values, DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

DescriptionThis operation reads a sequence of Foo samples of the next single instance from theSPACE_FooDataReader.

Parametersin SPACE_FooDataReader _this - the SPACE_FooDataReader object on

which the operation is operated.inout DDS_sequence_Foo *data_values - the returned sample data

sequence. data_values is also used as an input to control the behaviour of thisoperation.

485API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

inout DDS_SampleInfoSeq *info_seq - the returned DDS_SampleInfostructure sequence. info_seq is also used as an input to control the behaviourof this operation.

in const DDS_long max_samples - the maximum number of samples that isreturned.

in const DDS_InstanceHandle_t a_handle - the current single instance, thereturned samples belong to the next single instance.

in const DDS_SampleStateMask sample_states - a mask, which selectsonly those samples with the desired sample states.

in const DDS_ViewStateMask view_states - a mask, which selects onlythose samples with the desired view states.

in const DDS_InstanceStateMask instance_states - a mask, whichselects only those samples with the desired instance states.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED , DDS_RETCODE_PRECONDITION_NOT_MET o rDDS_RETCODE_NO_DATA.

Detailed DescriptionThis operation reads a sequence of Foo samples of a single instance from theSPACE_FooDataReader. T h e b e h a v i o u r i s s i m i l a r t oSPACE_FooDataReader_read_instance (all samples returned belong to asingle instance) except that the actual instance is not directly specified. Rather thesamples will all belong to the ‘next’ instance with instance_handle ‘greater’(according to some internal-defined order) than a_handle, that has availablesamples. The data is returned by the parameters data_values and info_seq. Thecorresponding DDS_SampleInfo.instance_handle in info_seq will has thevalue of the next instance with respect to a_handle.

Instance OrderThe internal-defined order is not important and is implementation specific. Theimportant thing is that, according to the Data Distribution Service, all instances areordered relative to each other. This ordering is between the instances, that is, it doesnot depend on the actual samples received. For the purposes of this explanation it is‘as if ’ each instance handle was represented as a unique integer.

486API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

The behaviour of SPACE_FooDataReader_read_next_instance is ‘as if ’ theDDS_DataReader invoked SPACE_FooDataReader_read_instance passingthe smallest instance_handle among all the ones that:• are greater than a_handle• have available samples (i.e. samples that meet the constraints imposed by the

specified states).The special value DDS_HANDLE_NIL is guaranteed to be ‘less than’ any validinstance_handle . S o th e u s e o f t h e p a r a m e t e r v a l u ea_handle==DDS_HANDLE_NIL will return the samples for the instance which hasthe smallest instance_handle among all the instances that contains availablesamples.

Typical useThe operation SPACE_FooDataReader_read_next_instance is intended to beused in an application-driven iteration where the application starts by passinga_handle==DDS_HANDLE_NIL, examines the samples returned, and then uses theinstance_handle returned in the DDS_SampleInfo as the value of a_handleargument to the next call to SPACE_FooDataReader_read_next_instance.The iteration continues until SPACE_FooDataReader_read_next_instancereturns the return value DDS_RETCODE_NO_DATA.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - a sequence of data values is available.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - either or both of data_values or info_seq

is an invalid pointer or a_handle is not a valid handle.• DDS_RETCODE_ALREADY_DELETED - the SPACE_FooDataReader has already

been deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_NOT_ENABLED - the SPACE_FooDataReader is not enabled.• DDS_RETCODE_PRECONDITION_NOT_MET - one of the following is true:

- the max_samples>_maximum and max_samples is notDDS_LENGTH_UNLIMITED.

487API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

- one or more values of _length, _maximum, and _release for the twosequences are not identical.

- the _maximum>0 and the _release==FALSE. - the handle has not been registered with this DataReader.

• DDS_RETCODE_NO_DATA - no samples that meet the constraints are available.

3.5.2.69 SPACE_FooDataReader_read_next_instance_w_condition

Synopsis#include <Space.h>

DDS_ReturnCode_t SPACE_FooDataReader_read_next_instance_w_condition

(SPACE_FooDataReader _this, DDS_sequence_Foo *data_values, DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_ReadCondition a_condition);

DescriptionThis operation reads a sequence of Foo samples of the next single instance from theSPACE_FooDataReader.

Parametersin SPACE_FooDataReader _this - the SPACE_FooDataReader object on

which the operation is operated.inout DDS_sequence_Foo *data_values - the returned sample data

sequence. data_values is also used as an input to control the behaviour of thisoperation.

inout DDS_SampleInfoSeq *info_seq - the returned DDS_SampleInfostructure sequence. info_seq is also used as an input to control the behaviourof this operation.

in const DDS_long max_samples - the maximum number of samples that isreturned.

in const DDS_InstanceHandle_t a_handle - the current single instance, thereturned samples belong to the next single instance.

in const DDS_ReadCondition a_condition - a po in t e r t o aDDS_ReadCondition or DDS_QueryCondition which filters the databefore it is returned by the read operation.

488API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED , DDS_RETCODE_PRECONDITION_NOT_MET o rDDS_RETCODE_NO_DATA.

Detailed DescriptionThis operation reads a sequence of Foo samples of a single instance from theSPACE_FooDataReader, filtered by a DDS_ReadCondition orDDS_QueryCondition . Th e b e h a v io u r i s i d e n t i c a l t oSPACE_FooDataReader_read_next_instance except for that the samplesare filtered by a DDS_ReadCondition or DDS_QueryCondition. When using aDDS_ReadCondition , t h e r e su l t i s t he s ame a s t heSPACE_FooDataReader_read_next_instance operation with the same stateparameters filled in as for the DDS_create_readcondition. In this way, theapplication can avoid repeating the same parameters, specified when creating theDDS_ReadCondition. When using a DDS_QueryCondition, a content basedfi l ter ing can be done. When ei ther using a DDS_ReadCondition orDDS_QueryCondition , t h e c o n d i t i o n m u s t b e c r e a t e d b y t h i sSPACE_FooDataReader. Otherwise the operation will fail and returnsDDS_RETCODE_PRECONDITION_NOT_MET.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - a sequence of data values is available.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - one or more of the data_values, orinfo_seq and a_condition parameters is an invalid pointer or a_handle isnot a valid handle.

• DDS_RETCODE_ALREADY_DELETED - the SPACE_FooDataReader has alreadybeen deleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_NOT_ENABLED - the SPACE_FooDataReader is not enabled.• DDS_RETCODE_PRECONDITION_NOT_MET - one of the following is true:

489API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

- the DDS_ReadCondition or DDS_QueryCondition is not attached to thisSPACE_FooDataReader.

- the max_samples>_maximum and max_samples is notDDS_LENGTH_UNLIMITED.

- one or more values of _length, _maximum, and _release for the twosequences are not identical.

- the _maximum>0 and the _release==FALSE. - the handle has not been registered with this DataReader.

• DDS_RETCODE_NO_DATA - no samples that meet the constraints are available.

3.5.2.70 SPACE_FooDataReader_read_next_sample

Synopsis#include <Space.h>

DDS_ReturnCode_t SPACE_FooDataReader_read_next_sample

(SPACE_FooDataReader _this, Foo *data_values, DDS_SampleInfo *sample_info);

NOTE: This operation is not yet implemented. It is scheduled for a future release.

3.5.2.71 SPACE_FooDataReader_read_w_condition

Synopsis#include <Space.h>

DDS_ReturnCode_t SPACE_FooDataReader_read_w_condition

(SPACE_FooDataReader _this, DDS_sequence_Foo *data_values, DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_ReadCondition a_condition);

DescriptionThis operation reads a sequence of Foo samples from the SPACE_FooDataReader,filtered by a DDS_ReadCondition or DDS_QueryCondition.

Parametersin SPACE_FooDataReader _this - the SPACE_FooDataReader object on

which the operation is operated.

490API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

inout DDS_sequence_Foo *data_values - the returned sample datasequence. data_values is also used as an input to control the behaviour of thisoperation.

inout DDS_SampleInfoSeq *info_seq - the returned DDS_SampleInfostructure sequence. info_seq is also used as an input to control the behaviourof this operation.

in const DDS_long max_samples - the maximum number of samples that isreturned.

in const DDS_ReadCondition a_condition - a po in t e r t o aDDS_ReadCondition or DDS_QueryCondition which filters the data beforeit is returned by the SPACE_FooDataReader_read operation.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED , DDS_RETCODE_PRECONDITION_NOT_MET o rDDS_RETCODE_NO_DATA.

Detailed DescriptionThis operation reads a sequence of Foo samples from the SPACE_FooDataReader,filtered by a DDS_ReadCondition or DDS_QueryCondition. The conditionpointer from both SPACE_FooDataReader_create_readcondition orSPACE_FooDataReader_create_querycondition may be used. Thebehaviour is identical to SPACE_FooDataReader_read except for that thesamples are filtered by a DDS_ReadCondition or DDS_QueryCondition. Whenus in g a DDS_ReadCondition , t h e r e s u l t i s t h e s a m e a s t h eSPACE_FooDataReader_read operation with the same state parameters filled inas for the SPACE_FooDataReader_create_readcondition. In this way, theapplication can avoid repeating the same parameters, specified when creating theDDS_ReadCondition. When using a DDS_QueryCondition, a content basedfi l ter ing can be done. When ei ther using a DDS_ReadCondition orDDS_QueryCondition , t h e c o n d i t i o n m u s t b e c r e a t e d b y t h i sSPACE_FooDataReader. Otherwise the operation will fail and returnsDDS_RETCODE_PRECONDITION_NOT_MET.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - a sequence of data values is available.

491API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - one or more of the data_values, orinfo_seq and a_condition parameters is an invalid pointer.

• DDS_RETCODE_ALREADY_DELETED - the SPACE_FooDataReader has alreadybeen deleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_NOT_ENABLED - the SPACE_FooDataReader is not enabled.• DDS_RETCODE_PRECONDITION_NOT_MET - one of the following is true:

- the DDS_ReadCondition or DDS_QueryCondition is not attached to thisSPACE_FooDataReader.

- the max_samples>_maximum and max_samples is notDDS_LENGTH_UNLIMITED.

- one or more values of _length, _maximum, and _release for the twosequences are not identical.

- the _maximum>0 and the _release==FALSE.• DDS_RETCODE_NO_DATA - no samples that meet the constraints are available.

3.5.2.72 SPACE_FooDataReader_return_loan

Synopsis#include <Space.h>

DDS_ReturnCode_t SPACE_FooDataReader_return_loan

(SPACE_FooDataReader _this, DDS_sequence_Foo *data_values, DDS_SampleInfoSeq *info_seq);

DescriptionThis operation indicates to the DDS_DataReader that the application is doneaccessing the sequence of data_values and info_seq.

Parametersin SPACE_FooDataReader _this - the SPACE_FooDataReader object on

which the operation is operated.inout DDS_sequence_Foo *data_values - the sample data sequence which

was loaned from the DDS_DataReader.

492API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

inout DDS_SampleInfoSeq *info_seq - the DDS_SampleInfo structuresequence which was loaned from the DDS_DataReader.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED or DDS_RETCODE_PRECONDITION_NOT_MET.

Detailed DescriptionThis operation indicates to the SPACE_FooDataReader that the application is doneaccessing the sequence of data_values and info_seq obtained by some earlieri nv oc a t i o n o f t h e op e r a t i on SPACE_FooDataReader_read o rSPACE_FooDataReader_take (or any of the similar operations) on theSPACE_FooDataReader.The data_values and info_seq must belong to a single related pair; that is, theyshould correspond to a pair returned from a single call to the operationSPACE_FooDataReader_read or SPACE_FooDataReader_take . Thedata_values and info_seq must also have been obtained from the sameDDS_DataReader to which they are returned. If either of these conditions is notmet the operation will fail and returns DDS_RETCODE_PRECONDITION_NOT_MET.

Buffer LoanThe operation SPACE_FooDataReader_return_loan allows implementations ofthe SPACE_FooDataReader_read and SPACE_FooDataReader_takeoperations to “loan” buffers from the Data Distribution Service to the applicationand in this manner provide “zero-copy” access to the data. During the loan, the DataDistribution Service will guarantee that the data_values and info_seq are notmodified.It is not necessary for an application to return the loans immediately after calling theoperation SPACE_FooDataReader_read or SPACE_FooDataReader_take.However, as these buffers correspond to internal resources inside theDDS_DataReader, the application should not retain them indefinitely.

Calling SPACE_FooDataReader_return_loanThe use of the SPACE_FooDataReader_return_loan operation is onlynecessary if the call to the operation SPACE_FooDataReader_read orSPACE_FooDataReader_take “loaned” buffers to the application. This onlyoccurs if the data_values and info_seq sequences had _maximum=0 at the timethe operation SPACE_FooDataReader_read or SPACE_FooDataReader_take

493API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

was called. The application may also examine the ‘_release’ property of thecollection to determine where there is an outstanding loan. However, calling theoperation SPACE_FooDataReader_return_loan on a pair of sequences thatdoes not have a loan is safe and has no side effects.I f the pair of sequences had a loan , upon re turn f rom the operat ionSPACE_FooDataReader_return_loan the pair of sequences has _maximum=0.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the DDS_DataReader is informed that the sequences will

not be used any more.• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - either or both of data_values or info_seq

is an invalid pointer.• DDS_RETCODE_ALREADY_DELETED - the SPACE_FooDataReader has already

been deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_NOT_ENABLED - the SPACE_FooDataReader is not enabled.• DDS_RETCODE_PRECONDITION_NOT_MET - one of the following is true:

- the data_values and info_seq do not belong to a single related pair. - the data_values and info_seq were not obtained from thisSPACE_FooDataReader.

3.5.2.73 SPACE_FooDataReader_set_listener (inherited)This operation is inherited and therefore not described here. See the classDDS_DataReader for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReader_set_listener (SPACE_FooDataReader _this, const struct DDS_DataReaderListener *a_listener, const DDS_StatusMask mask);

494API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

3.5.2.74 SPACE_FooDataReader_set_qos (inherited)This operation is inherited and therefore not described here. See the classDDS_DataReader for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReader_set_qos (SPACE_FooDataReader _this, const DDS_DataReaderQos *qos);

3.5.2.75 SPACE_FooDataReader_take

Synopsis#include <Space.h>

DDS_ReturnCode_t SPACE_FooDataReader_take

(SPACE_FooDataReader _this, DDS_sequence_Foo *data_values, DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

DescriptionThis operation reads a sequence of Foo samples from the SPACE_FooDataReaderand by doing so, removes the data from the SPACE_FooDataReader.

Parametersin SPACE_FooDataReader _this - the SPACE_FooDataReader object on

which the operation is operated.inout DDS_sequence_Foo *data_values - the returned sample data

sequence. data_values is also used as an input to control the behaviour of thisoperation.

inout DDS_SampleInfoSeq *info_seq - the returned DDS_SampleInfostructure sequence. info_seq is also used as an input to control the behaviourof this operation.

in const DDS_long max_samples - the maximum number of samples that isreturned.

in const DDS_SampleStateMask sample_states - a mask, which selectsonly those samples with the desired sample states.

495API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

in const DDS_ViewStateMask view_states - a mask, which selects onlythose samples with the desired view states.

in const DDS_InstanceStateMask instance_states - a mask, whichselects only those samples with the desired instance states.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED , DDS_RETCODE_PRECONDITION_NOT_MET o rDDS_RETCODE_NO_DATA.

Detailed DescriptionThis operation reads a sequence of Foo samples from the SPACE_FooDataReaderand by doing so, removes the data from the SPACE_FooDataReader, so it can notb e r e a d o r t a k e n a g a i n . T h e b e h a v i o u r i s i d e n t i c a l t oSPACE_FooDataReader_read except for that the samples are removed from theSPACE_FooDataReader.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - a sequence of data values is available and removed from theSPACE_FooDataReader.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - either or both of data_values or info_seq

is an invalid pointer.• DDS_RETCODE_ALREADY_DELETED - the SPACE_FooDataReader has already

been deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_NOT_ENABLED - the SPACE_FooDataReader is not enabled.• DDS_RETCODE_PRECONDITION_NOT_MET - one of the following is true:

- the max_samples>_maximum and max_samples is notDDS_LENGTH_UNLIMITED.

496API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

- one or more values of _length, _maximum, and _release for the twosequences are not identical.

- the _maximum>0 and the _release==FALSE.• DDS_RETCODE_NO_DATA - no samples that meet the constraints are available.

3.5.2.76 SPACE_FooDataReader_take_instance

Synopsis#include <Space.h>

DDS_ReturnCode_t SPACE_FooDataReader_take_instance

(SPACE_FooDataReader _this, DDS_sequence_Foo *data_values, DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

DescriptionThis operation reads a sequence of Foo samples of a single instance from theSPACE_FooDataReader and by doing so, removes the data from theSPACE_FooDataReader.

Parametersin SPACE_FooDataReader _this - the SPACE_FooDataReader object on

which the operation is operated.inout DDS_sequence_Foo *data_values - the returned sample data

sequence. data_values is also used as an input to control the behaviour of thisoperation.

inout DDS_SampleInfoSeq *info_seq - the returned DDS_SampleInfostructure sequence. info_seq is also used as an input to control the behaviourof this operation.

in const DDS_long max_samples - the maximum number of samples that isreturned.

in const DDS_InstanceHandle_t a_handle - the single instance, thesamples belong to.

in const DDS_SampleStateMask sample_states - a mask, which selectsonly those samples with the desired sample states.

497API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

in const DDS_ViewStateMask view_states - a mask, which selects onlythose samples with the desired view states.

in const DDS_InstanceStateMask instance_states - a mask, whichselects only those samples with the desired instance states.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED , DDS_RETCODE_PRECONDITION_NOT_MET o rDDS_RETCODE_NO_DATA.

Detailed DescriptionThis operation reads a sequence of Foo samples of a single instance from theSPACE_FooDataReader and by doing so, removes the data from theSPACE_FooDataReader, so it can not be read or taken again. The behaviour isidentical to SPACE_FooDataReader_read_instance except for that the samplesare removed from the SPACE_FooDataReader.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - a sequence of data values is available and removed from theSPACE_FooDataReader.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - either or both of data_values or info_seq

is an invalid pointer or a_handle is not a valid handle.• DDS_RETCODE_ALREADY_DELETED - the SPACE_FooDataReader has already

been deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_NOT_ENABLED - the SPACE_FooDataReader is not enabled.• DDS_RETCODE_PRECONDITION_NOT_MET - one of the following is true:

- the max_samples>_maximum and max_samples is notDDS_LENGTH_UNLIMITED.

498API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

- one or more values of _length, _maximum, and _release for the twosequences are not identical.

- the _maximum>0 and the _release==FALSE. - the handle ==DDS_HANDLE_NIL. - the handle has not been registered with this DataReader.

• DDS_RETCODE_NO_DATA - no samples that meet the constraints are available.

3.5.2.77 SPACE_FooDataReader_take_next_instance

Synopsis#include <Space.h>

DDS_ReturnCode_t SPACE_FooDataReader_take_next_instance

(SPACE_FooDataReader _this, DDS_sequence_Foo *data_values, DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

DescriptionThis operation reads a sequence of Foo samples of the next single instance from theSPACE_FooDataReader and by doing so, removes the data from theSPACE_FooDataReader.

Parametersin SPACE_FooDataReader _this - the SPACE_FooDataReader object on

which the operation is operated.inout DDS_sequence_Foo *data_values - the returned sample data

sequence. data_values is also used as an input to control the behaviour of thisoperation.

inout DDS_SampleInfoSeq *info_seq - the returned DDS_SampleInfostructure sequence. info_seq is also used as an input to control the behaviourof this operation.

in const DDS_long max_samples - the maximum number of samples that isreturned.

in const DDS_InstanceHandle_t a_handle - the current single instance, thereturned samples belong to the next single instance.

499API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

in const DDS_SampleStateMask sample_states - a mask, which selectsonly those samples with the desired sample states.

in const DDS_ViewStateMask view_states - a mask, which selects onlythose samples with the desired view states.

in const DDS_InstanceStateMask instance_states - a mask, whichselects only those samples with the desired instance states.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED , DDS_RETCODE_PRECONDITION_NOT_MET o rDDS_RETCODE_NO_DATA.

Detailed DescriptionThis operation reads a sequence of Foo samples of a single instance from theSPACE_FooDataReader and by doing so, removes the data from theSPACE_FooDataReader, so it can not be read or taken again. The behaviour isidentical to SPACE_FooDataReader_read_next_instance except for that thesamples are removed from the SPACE_FooDataReader.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - a sequence of data values is available and removed from theSPACE_FooDataReader.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - either or both of data_values or info_seq

is an invalid pointer or a_handle is not a valid handle.• DDS_RETCODE_ALREADY_DELETED - the SPACE_FooDataReader has already

been deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.• DDS_RETCODE_NOT_ENABLED - the SPACE_FooDataReader is not enabled.• DDS_RETCODE_PRECONDITION_NOT_MET - one of the following is true:

500API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

- the max_samples>_maximum and max_samples is notDDS_LENGTH_UNLIMITED.

- one or more values of _length, _maximum, and _release for the twosequences are not identical.

- the _maximum>0 and the _release==FALSE. - the handle has not been registered with this DataReader.

• DDS_RETCODE_NO_DATA - no samples that meet the constraints are available.

3.5.2.78 SPACE_FooDataReader_take_next_instance_w_condition

Synopsis#include <Space.h>

DDS_ReturnCode_t SPACE_FooDataReader_take_next_instance_w_condition

(SPACE_FooDataReader _this, DDS_sequence_Foo *data_values, DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_ReadCondition a_condition);

DescriptionThis operation reads a sequence of Foo samples of the next single instance from theSPACE_FooDataReader and by doing so, removes the data from theSPACE_FooDataReader.

Parametersin SPACE_FooDataReader _this - the SPACE_FooDataReader object on

which the operation is operated.inout DDS_sequence_Foo *data_values - the returned sample data

sequence. data_values is also used as an input to control the behaviour of thisoperation.

inout DDS_SampleInfoSeq *info_seq - the returned DDS_SampleInfostructure sequence. info_seq is also used as an input to control the behaviourof this operation.

in const DDS_long max_samples - the maximum number of samples that isreturned.

in const DDS_InstanceHandle_t a_handle - the current single instance, thereturned samples belong to the next single instance.

501API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

in const DDS_ReadCondition a_condition - a po in t e r t o aDDS_ReadCondition or DDS_QueryCondition which filters thedata before it is returned by the read operation.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED , DDS_RETCODE_PRECONDITION_NOT_MET o rDDS_RETCODE_NO_DATA.

Detailed DescriptionThis operation reads a sequence of Foo samples of a single instance from theSPACE_FooDataReader , f i l t e r e d b y a DDS_ReadCondition o rDDS_QueryCondition and by doing so, removes the data f rom theSPACE_FooDataReader, so it can not be read or taken again. The behaviour isidentical to SPACE_FooDataReader_read_next_instance_w_conditionexcept for that the samples are removed from the SPACE_FooDataReader.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - a sequence of data values is available and removed from theSPACE_FooDataReader.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - one or more of the data_values,info_seq and a_condition parameters is an invalid pointer or a_handle isnot a valid handle.

• DDS_RETCODE_ALREADY_DELETED - the SPACE_FooDataReader has alreadybeen deleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_NOT_ENABLED - the SPACE_FooDataReader is not enabled.• DDS_RETCODE_PRECONDITION_NOT_MET - one of the following is true:

- the DDS_ReadCondition or DDS_QueryCondition is not attached to thisSPACE_FooDataReader.

502API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

- the max_samples>_maximum and max_samples is notDDS_LENGTH_UNLIMITED.

- one or more values of _length, _maximum, and _release for the twosequences are not identical.

- the _maximum>0 and the _release==FALSE. - the handle has not been registered with this DataReader.

• DDS_RETCODE_NO_DATA - no samples that meet the constraints are available.

3.5.2.79 SPACE_FooDataReader_take_next_sample

Synopsis#include <Space.h>

DDS_ReturnCode_t SPACE_FooDataReader_take_next_sample

(SPACE_FooDataReader _this, Foo *data_values, DDS_SampleInfo *sample_info);

NOTE: This operation is not yet implemented. It is scheduled for a future release.

3.5.2.80 SPACE_FooDataReader_take_w_condition

Synopsis#include <Space.h>

DDS_ReturnCode_t SPACE_FooDataReader_take_w_condition

(SPACE_FooDataReader _this, DDS_sequence_Foo *data_values, DDS_SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_ReadCondition a_condition);

DescriptionThis operation reads a sequence of Foo samples from the SPACE_FooDataReader,filtered by a DDS_ReadCondition or DDS_QueryCondition and by doing so,removes the data from the SPACE_FooDataReader.

Parametersin SPACE_FooDataReader _this - the SPACE_FooDataReader object on

which the operation is operated.inout DDS_sequence_Foo *data_values - the returned sample data

sequence. data_values is also used as an input to control the behaviour of thisoperation.

503API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

inout DDS_SampleInfoSeq *info_seq - the returned DDS_SampleInfostructure sequence. info_seq is also used as an input to control the behaviourof this operation.

in const DDS_long max_samples - the maximum number of samples that isreturned.

in const DDS_ReadCondition a_condition - a po in t e r t o aDDS_ReadCondition or DDS_QueryCondition which filters the data beforeit is returned by the SPACE_FooDataReader_read operation.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES, DDS_RETCODE_NOT_ENABLED , DDS_RETCODE_PRECONDITION_NOT_MET o rDDS_RETCODE_NO_DATA.

Detailed DescriptionThis operation reads a sequence of Foo samples from the SPACE_FooDataReader,filtered by a DDS_ReadCondition or DDS_QueryCondition and by doing so,removes the data from the SPACE_FooDataReader, so it can not be read or takena g a i n . T h e b e h a v i o u r i s i d e n t i c a l t oSPACE_FooDataReader_read_w_condition except for that the samples areremoved from the SPACE_FooDataReader.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - a sequence of data values is available and removed from theSPACE_FooDataReader.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - one or more of the data_values, orinfo_seq and a_condition parameters is an invalid pointer.

• DDS_RETCODE_ALREADY_DELETED - the SPACE_FooDataReader has alreadybeen deleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• DDS_RETCODE_NOT_ENABLED - the SPACE_FooDataReader is not enabled.

504API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

• DDS_RETCODE_PRECONDITION_NOT_MET - one of the following is true: - the DDS_ReadCondition or DDS_QueryCondition is not attached to thisSPACE_FooDataReader.

- the max_samples>_maximum and max_samples is notDDS_LENGTH_UNLIMITED.

- one or more values of _length, _maximum, and _release for the twosequences are not identical.

- the _maximum>0 and the _release==FALSE.• DDS_RETCODE_NO_DATA - no samples that meet the constraints are available.

3.5.2.81 SPACE_FooDataReader_wait_for_historical_data (inherited)This operation is inherited and therefore not described here. See the classDDS_DataReader for further explanation.

Synopsis#include <Space.h>

DDS_ReturnCode_t SPACE_FooDataReader_wait_for_historical_data

(SPACE_FooDataReader _this, const DDS_Duration_t *max_wait);

3.5.2.82 SPACE_FooDataReader_wait_for_historical_data_w_condition (inherited)

This operation is inherited and therefore not described here. See the classDataReader for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReader_wait_for_historical_data_w_condition (Space_FooDataReader _this, const DDS_string filter_expression, const DDS_StringSeq* filter_parameters, const DDS_Time_t* min_source_timestamp, const DDS_Time_t* max_source_timestamp const DDS_ResourceLimitsQosPolicy* resource_limits, const DDS_Duration_t* max_wait)

3.5.3 Class DDS_DataSampleA DDS_DataSample represents an atom of data information (i.e. one value for anin s t ance ) a s r e tu rne d by t he DDS_DataReader ’sDDS_DataReader_read/SPACE_FooDataReader_take operations. It consists

505API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

of two parts: A DDS_SampleInfo and the Data itself. The Data part is the data asproduced by a DDS_Publisher. The DDS_SampleInfo part contains additionalinformation related to the data provided by the Data Distribution Service.

3.5.4 Struct DDS_SampleInfoThe struct DDS_SampleInfo represents the additional information thataccompanies the data in each sample that is read or taken.The interface description of this struct is as follows:

struct DDS_SampleInfo{

DDS_SampleStateKind sample_state;DDS_ViewStateKind view_state;DDS_InstanceStateKind instance_state;DDS_Time_t source_timestamp;DDS_InstanceHandle_t instance_handle;DDS_InstanceHandle_t publication_handle;DDS_long disposed_generation_count;DDS_long no_writers_generation_count;DDS_long sample_rank;DDS_long generation_rank;DDS_long absolute_generation_rank;DDS_boolean valid_data;DDS_Time_t reception_timestamp;

};/* * implemented API operations * <no operations> */

The next paragraph describes the usage of the DDS_SampleInfo struct.

3.5.4.1 DDS_SampleInfo

Synopsis#include <dds_dcps.h>struct DDS_SampleInfo { DDS_SampleStateKind sample_state; DDS_ViewStateKind view_state; DDS_InstanceStateKind instance_state; DDS_Time_t source_timestamp; DDS_InstanceHandle_t instance_handle; DDS_InstanceHandle_t publication_handle; DDS_long disposed_generation_count; DDS_long no_writers_generation_count; DDS_long sample_rank; DDS_long generation_rank; DDS_long absolute_generation_rank;

506API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

DDS_boolean valid_data; DDS_Time_t reception_timestamp; };

DescriptionThe struct DDS_SampleInfo represents the additional information thataccompanies the data in each sample that is read or taken.

AttributesDDS_SampleStateKind sample_state - whether or not the corresponding data

sample has already been read.DDS_ViewStateKind view_state - whether the DDS_DataReader has already

seen samples of the most-current generation of the related instance.DDS_InstanceStateKind instance_state - whether the instance is alive, has

no writers or is disposed of.DDS_Time_t source_timestamp - t h e t i m e p r o v i d e d b y t h e

DDS_DataWriter when the sample was written.DDS_InstanceHandle_t instance_handle - the handle that identifies locally

the corresponding instance.DDS_InstanceHandle_t publication_handle - the handle that identifies

locally the DDS_DataWriter that modified the instance. In fact it is aninstance_handle of the built-in DCPSPublication sample that describesthis DDS_DataWriter. It can be used as a parameter to the DDS_DataReader_get_matched_publication_data operation to obtain this built-inDCPSPublication sample.

DDS_long disposed_generation_count - the number of times the instancehas become alive after it was disposed of explicitly by a DDS_DataWriter.

DDS_long no_writers_generation_count - the number of times the instancehas become al ive af ter i t was disposed of because there were noDDS_DataWriter objects.

DDS_long sample_rank - the number of samples related to the same instance thatare found in the collection returned by a DDS_DataReader_read orDDS_DataReader_take operation.

DDS_long generation_rank - the generation difference between the time thesample was received and the time the most recent sample in the collection wasreceived.

DDS_long absolute_generation_rank - the generation difference betweenthe time the sample was received and the time the most recent sample wasreceived.

507API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

DDS_boolean valid_data - whether the DataSample contains any meanigfuldata. If not, the sample is only used to communicate a change in theinstance_state of the instance.

DDS_Time_t reception_timestamp - the time provided by the DataReaderwhen the sample was received.

Detailed DescriptionThe struct DDS_SampleInfo represents the additional information thataccompanies the data in each sample that is read or taken.

Sample InformationThe struct DDS_SampleInfo represents the additional information thataccompanies the data in each sample that is read or taken.

GenerationsA generation is defined as: ‘the number of times an instance has become alive (withinstance_state==DDS_ALIVE_INSTANCE_STATE) at the time the sample wasreceived’. Note that the generation counters are initialized to zero when a Readerfirst detects a never-seen-before instance.Two types of generations are distinguished: disposed_generation_count andno_writers_generation_count.A f t e r a DDS_DataWriter d i s p o s e s a n i n s t a n c e , t h edisposed_generation_count for all Readers that already knew that instancewill be incremented the next time the instance is written again.If the DDS_DataReader detects that there are no live DDS_DataWriter entities,t he instance_state o f t he sample_info w i l l c h a n g e f r o mDDS_ALIVE_INSTANCE_STATE to DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE . T h e n e x t t im e th e in s t a n c e i s w r i t t e n ,no_writers_generation_count will be incremented.

Sample InformationDDS_SampleInfo is the additional information that accompanies the data in eachsample that is read or taken. It contains the following information:• sample_state (DDS_READ_SAMPLE_STATE or DDS_NOT_READ_SAMPLE_STATE) indicates whether or not the corresponding data sample has already beenread

• view_state, (DDS_NEW_VIEW_STATE, or DDS_NOT_NEW_VIEW_STATE)indicates whether the DDS_DataReader has already seen samples of themost-current generation of the related instance

508API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

• instance_state (DDS_ALIVE_INSTANCE_STATE, DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE, or DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE) indicates whether the instance is alive, has no writers or if it has beendisposed of: - DDS_ALIVE_INSTANCE_STATE if this instance is currently in existence - DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE if this instance was disposed

of by a DDS_DataWriter - DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE none of theDDS_DataWriter objects currently “alive” (according to theDDS_LivelinessQosPolicy) are writing the instance.

• source_timestamp indicates the time provided by the DDS_DataWriter whenthe sample was written

• instance_handle indicates locally the corresponding instance• publication_handle is used by the DDS implementation to locally identify

the corresponding source DataWriter. You can access more detailed informationabout this particular publication by passing its publication_handle to eitherthe DDS_DataReader_get_matched_publication_data operation or to theDDS_PublicationBuiltinTopicDataDataReader_read_instanceoperation on the built-in reader for the “DCPSPublication” topic. Be aware that since DDS_InstanceHandle_t is an opaque datatype, it does notnecessarily mean that the handle obtained from the publication_handle hasthe same value as the one that appears in the instance_handle field of theDDS_SampleInfo when retrieving the publication info through corresponding"DCPSPublication" built-in reader. You can’t just compare two handles todetermine whether they represent the same publication. If you want to knowwhether two handles actually do represent the same publication, use both handlesto retrieve their corresponding DDS_PublicationBuiltinTopicData samplesand then compare the key field of both samples.

• disposed_generation_count indicates the number of times the instance hasbecome alive after it was disposed of explicitly by a DDS_DataWriter, at thetime the sample was received

• no_writers_generation_count indicates the number of times the instancehas become alive after its instance_state has beenDDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE, at the time the sample wasreceived

• sample_rank indicates the number of samples related to the same instance thatfollow in the collection returned by a DDS_DataReader_read orDDS_DataReader_take operation

509API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

• generation_rank indicates the generation difference (number of times theinstance was disposed of and become alive again) between the time the samplewas received and the time the most recent sample in the collection (related to thesame instance) was received

• absolute_generation_rank indicates the generation difference (number oftimes the instance was disposed of and become alive again) between the time thesample was received and the time the most recent sample (which may not be in thereturned collection), related to the same instance, was received.

• valid_data indicates whether the corresponding data value contains anymeaningful data. If not, the data value is just a ‘dummy’ sample for which onlythe keyfields have been assigned. It is used to accompany the DDS_SampleInfothat communicates a change in the instance_state of an instance for whichthere is no ‘real’ sample available.

• reception_timestamp indicates the time provided by the DDS_DataReaderwhen the sample was inserted.NOTE: This is an OpenSplice-specific extension to the DDS_SampleInfo structand is not part of the DDS Specification.

3.5.5 DDS_SubscriberListener InterfaceSince a DDS_Subscriber is a kind of DDS_Entity, it has the ability to have aListener associated with it. In this case, the associated Listener should be oftype DDS_SubscriberListener. This interface must be implemented by theapplication. A user-defined class must be provided by the application which muste x t e n d f r o m t h e DDS_SubscriberListener c l a s s . A l lDDS_SubscriberListener operations must be implemented in the user-definedclass, it is up to the application whether an operation is empty or contains somefunctionality.

All operations for this interface must be implemented in the user-defined class, it isup to the application whether an operation is empty or contains some functionality.

The DDS_SubscriberListener provides a generic mechanism (actually acallback function) for the Data Distribution Service to notify the application ofrelevant asynchronous status change events, such as a missed deadline, violation ofa QosPolicy setting, etc. The DDS_SubscriberListener is related to changesin communication status.The interface description of this class is as follows:

/* * interface DDS_SubscriberListener *//* * inherited from class DDS_DataReaderListener

510API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

*//* void * DDS_SubscriberListener_on_requested_deadline_missed * (void *listener_data, * DDS_DataReader reader, * const DDS_RequestedDeadlineMissedStatus *status);

*//* void * DDS_SubscriberListener_on_requested_incompatible_qos * (void *listener_data, * DDS_DataReader reader, * const DDS_RequestedIncompatibleQosStatus *status); */

/* void * DDS_SubscriberListener_on_sample_rejected * (void *listener_data, * DDS_DataReader reader, * const DDS_SampleRejectedStatus *status); */

/* void * DDS_SubscriberListener_on_liveliness_changed * (void *listener_data, * DDS_DataReader reader, * const DDS_LivelinessChangedStatus *status); */

/* void * DDS_SubscriberListener_on_data_available * (void *listener_data, * DDS_DataReader reader); */

/* void * DDS_SubscriberListener_on_subscription_matched * (void *listener_data, * DDS_DataReader reader, * const DDS_SubscriptionMatchedStatus *status); */

/* void * DDS_SubscriberListener_on_sample_lost * (void *listener_data, * DDS_DataReader reader, * const DDS_SampleLostStatus *status); *//* * abstract external operations */

511API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

void DDS_SubscriberListener_on_data_on_readers

(void *listener_data, DDS_Subscriber subs);

/* * implemented API operations */

struct DDS_SubscriberListener * DDS_SubscriberListener__alloc (void);

The next paragraphs list all DDS_SubscriberListener operations. The inheritedoperations are listed but not fully described because they are not implemented in thisclass. The full description of these operations is given in the classes from which theyare inherited. The abstract operation is fully described since it must be implementedby the application.

3.5.5.1 DDS_SubscriberListener__alloc

Synopsis#include <dds_dcps.h>struct DDS_SubscriberListener * DDS_SubscriberListener__alloc (void);

DescriptionThis operation creates a new DDS_SubscriberListener.

Parameters<none>

Return Valuestruct DDS_SubscriberListener * - Return value is the handle to the

newly-created DDS_SubscriberListener. In case of an error, aDDS_OBJECT_NIL pointer is returned.

Detailed DescriptionThi s ope ra t i on c r ea t e s a new DDS_SubscriberListener. T h eDDS_SubscriberListener must be created using this operation. In other words,t h e a p p l i c a t i o n i s n o t a l l o w e d t o d e c l a r e a n o b j e c t o f t y p eDDS_SubscriberListener. When the application wants to release theDDS_SubscriberListener it must be released using DDS_free.I n c a s e t h e r e a r e i n s u ff i c i e n t r e s o u r c e s a v a i l a b l e t o a l l o c a t e t h eDDS_SubscriberListener, a DDS_OBJECT_NIL pointer is returned instead.

512API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

3.5.5.2 DDS_SubscriberListener_on_data_available (inherited, abstract)This operation is inherited and therefore not described here. See the classDDS_DataReaderListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_SubscriberListener_on_data_available (void *listener_data, DDS_DataReader reader);

3.5.5.3 DDS_SubscriberListener_on_data_on_readers (abstract)

Synopsis#include <dds_dcps.h>void DDS_SubscriberListener_on_data_on_readers (void *listener_data, DDS_Subscriber subs);

DescriptionThis operation must be implemented by the application and is called by the DataDistribution Service when new data is available.

Parametersinout void *listener_data - a pointer to a user-defined object which may be

used for identification of the Listener.in DDS_Subscriber subs - contain a pointer to the DDS_Subscriber for

which data is available (this is an input to the application provided by the DataDistribution Service).

Return Value<none>

Detailed DescriptionThis operation is the external operation (interface, which must be implemented bythe application) that is called by the Data Distribution Service when new data isavailable for this DDS_Subscriber. The implementation may be left empty whenthis functionality is not needed. This operation will only be called when the relevantDDS_SubscriberListener i s i n s t a l l e d a n d e n a b le d f o r t h eDDS_DATA_ON_READERS_STATUS.

513API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

The Data Distribution Service will provide a pointer to the DDS_Subscriber in theparameter subs for use by the application.T h e s t a t u s e s DDS_DATA_ON_READERS_STATUS a n dDDS_DATA_AVAILABLE_STATUS will occur together. In case these status changesoccur, the Data Distribution Service will look for an attached and activatedDDS_SubscriberListener or DDS_DomainParticipantListener (in thato r d e r ) f o r t h e DDS_DATA_ON_READERS_STATUS . I n c a s e t h eDDS_DATA_ON_READERS_STATUS can not be handled, the Data DistributionService will look for an attached and activated DDS_DataReaderListener,DDS_SubscriberListener or DDS_DomainParticipantListener for theDDS_DATA_AVAILABLE_STATUS (in that order).Note that if DDS_SubscriberListener_on_data_on_readers is called, thent h e D a t a D i s t r i b u t io n S e r v i c e w i l l n o t t r y t o c a l lDDS_SubscriberListener_on_data_available, however, the applicationcan force a cal l to the cal lback funct ion on_data_available ofDDS_DataReaderListener objects that have data by means of thenotify_datareaders operation.

3.5.5.4 DDS_SubscriberListener_on_liveliness_changed (inherited, abstract)This operation is inherited and therefore not described here. See the classDDS_DataReaderListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_SubscriberListener_on_liveliness_changed (void *listener_data, DDS_DataReader reader, const DDS_LivelinessChangedStatus *status);

3.5.5.5 DDS_SubscriberListener_on_requested_deadline_missed (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_DataReaderListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_SubscriberListener_on_requested_deadline_missed (void *listener_data, DDS_DataReader reader, const DDS_RequestedDeadlineMissedStatus *status);

514API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

3.5.5.6 DDS_SubscriberListener_on_requested_incompatible_qos (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_DataReaderListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_SubscriberListener_on_requested_incompatible_qos (void *listener_data, DDS_DataReader reader, const DDS_RequestedIncompatibleQosStatus *status) =0;

3.5.5.7 DDS_SubscriberListener_on_sample_lost (inherited, abstract)This operation is inherited and therefore not described here. See the classDDS_DataReaderListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_SubscriberListener_on_sample_lost (void *listener_data, DDS_DataReader reader, const DDS_SampleLostStatus *status);

NOTE: This operation is not yet implemented. It is scheduled for a future release.

3.5.5.8 DDS_SubscriberListener_on_sample_rejected (inherited, abstract)This operation is inherited and therefore not described here. See the classDDS_DataReaderListener for further explanation.

Synopsis#include <dds_dcps.h>void DDS_SubscriberListener_on_sample_rejected (void *listener_data, DDS_DataReader reader, const DDS_SampleRejectedStatus *status);

3.5.5.9 DDS_SubscriberListener_on_subscription_matched (inherited, abstract)

This operation is inherited and therefore not described here. See the classDDS_DataReaderListener for further explanation.

515API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Synopsis#include <dds_dcps.h>void DDS_SubscriberListener_on_subscription_matched (void *listener_data, DDS_DataReader reader, const DDS_SubscriptionMatchedStatus *status);

3.5.6 DDS_DataReaderListener interfaceSince a DDS_DataReader is a kind of DDS_Entity, it has the ability to have aListener associated with it. In this case, the associated Listener should be oftype DDS_DataReaderListener. This interface must be implemented by theapplication. A user-defined class must be provided by the application which muste x t e n d f r o m t h e DDS_DataReaderListener c l a s s . A l lDDS_DataReaderListener operations must be implemented in the user-definedclass, it is up to the application whether an operation is empty or contains somefunctionality.

All operations for this interface must be implemented in the user-defined class, it isup to the application whether an operation is empty or contains some functionality.

The DDS_DataReaderListener provides a generic mechanism (actually acallback function) for the Data Distribution Service to notify the application ofrelevant asynchronous status change events, such as a missed deadline, violation ofa QosPolicy setting, etc. The DDS_DataReaderListener is related to changesin communication status.The interface description of this class is as follows:

/* * interface DDS_DataReaderListener *//* * abstract external operations */

void DDS_DataReaderListener_on_requested_deadline_missed

(void *listener_data, DDS_DataReader reader,

const DDS_RequestedDeadlineMissedStatus *status);void DDS_DataReaderListener_on_requested_incompatible_qos

(void *listener_data, DDS_DataReader reader,

const DDS_RequestedIncompatibleQosStatus *status);

void

516API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

DDS_DataReaderListener_on_sample_rejected (void *listener_data,

DDS_DataReader reader, const DDS_SampleRejectedStatus *status);

void DDS_DataReaderListener_on_liveliness_changed

(void *listener_data, DDS_DataReader reader,

const DDS_LivelinessChangedStatus *status);

void DDS_DataReaderListener_on_data_available

(void *listener_data, DDS_DataReader reader);

void DDS_DataReaderListener_on_subscription_matched

(void *listener_data, DDS_DataReader reader,

const DDS_SubscriptionMatchedStatus *status);

void DDS_DataReaderListener_on_sample_lost

(void *listener_data, DDS_DataReader reader,

const DDS_SampleLostStatus *status);/* * implemented API operations */

struct DDS_DataReaderListener * DDS_DataReaderListener__alloc (void);

The next paragraphs describe the usage of all DDS_DataReaderListeneroperations. These abstract operations are fully described because they must beimplemented by the application.

3.5.6.1 DDS_DataReaderListener__alloc

Synopsis#include <dds_dcps.h>struct DDS_DataReaderListener * DDS_DataReaderListener__alloc (void);

DescriptionThis operation creates a new DDS_DataReaderListener.

517API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Parameters<none>

Return Valuestruct DDS_DataReaderListener * - Return value is the handle to the

newly-created DDS_DataReaderListener. In case of an error, aDDS_OBJECT_NIL pointer is returned.

Detailed DescriptionThi s ope ra t i on c r ea t e s a new DDS_DataReaderListener. T h eDDS_DataReaderListener must be created using this operation. In other words,t h e a p p l i c a t i o n i s n o t a l l o w e d t o d e c l a r e a n o b j e c t o f t y p eDDS_DataReaderListener. When the application wants to release theDDS_DataReaderListener it must be released using DDS_free.I n c a s e t h e r e a r e i n s u ff i c i e n t r e s o u r c e s a v a i l a b l e t o a l l o c a t e t h eDDS_DataReaderListener, a DDS_OBJECT_NIL pointer is returned instead.

3.5.6.2 DDS_DataReaderListener_on_data_available (abstract)

Synopsis#include <dds_dcps.h>void DDS_DataReaderListener_on_data_available (void *listener_data, DDS_DataReader reader);

DescriptionThis operation must be implemented by the application and is called by the DataDistribution Service when new data is available.

Parametersinout void *listener_data - a pointer to a user-defined object which may be

used for identification of the Listener.in DDS_DataReader reader - contain a pointer to the DDS_DataReader for

which data is available (this is an input to the application provided by the DataDistribution Service).

Return Value<none>

518API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Detailed DescriptionThis operation is the external operation (interface, which must be implemented bythe application) that is called by the Data Distribution Service when new data isavailable for this DDS_DataReader. The implementation may be left empty whenthis functionality is not needed. This operation will only be called when the relevantDDS_DataReaderListener i s i n s t a l l e d a n d e n a b le d f o r t h eDDS_DATA_AVAILABLE_STATUS.The Data Distribution Service will provide a pointer to the DDS_DataReader in theparameter reader for use by the application.T h e s t a tu s e s DDS_DATA_ON_READERS_STATUS a n dDDS_DATA_AVAILABLE_STATUS will occur together. In case these status changesoccur, the Data Distribution Service will look for an attached and activatedDDS_SubscriberListener or DDS_DomainParticipantListener (in thato r d e r ) f o r t h e DDS_DATA_ON_READERS_STATUS . I n c a s e t h eDDS_DATA_ON_READERS_STATUS can not be handled, the Data DistributionService will look for an attached and activated DDS_DataReaderListener,DDS_SubscriberListener or DDS_DomainParticipantListener for theDDS_DATA_AVAILABLE_STATUS (in that order).Note that if DDS_SubscriberListener_on_data_on_readers is called, thent h e D a t a D i s t r i b u t io n S e r v i c e w i l l n o t t r y t o c a l lDDS_DataReaderListener_on_data_available, however, the applicationcan force a call to the DDS_DataReader objects that have data by means of theDDS_Subscriber_notify_datareaders operation.

3.5.6.3 DDS_DataReaderListener_on_liveliness_changed (abstract)

Synopsis#include <dds_dcps.h>void DDS_DataReaderListener_on_liveliness_changed (void *listener_data, DDS_DataReader reader, const DDS_LivelinessChangedStatus *status);

DescriptionThis operation must be implemented by the application and is called by the DataDistribution Service when the liveliness of one or more DDS_DataWriter objectsthat were writing instances read through this DDS_DataReader has changed.

Parametersinout void *listener_data - a pointer to a user-defined object which may be

used for identification of the Listener.

519

API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

in DDS_DataReader reader - contain a pointer to the DDS_DataReader forwhich the liveliness of one or more DDS_DataWriter objects has changed(this is an input to the application provided by the Data Distribution Service).

in const DDS_LivelinessChangedStatus *status - contain theDDS_LivelinessChangedStatus struct (this is an input to the applicationprovided by the Data Distribution Service).

Return Value<none>

Detailed DescriptionThis operation is the external operation (interface, which must be implemented bythe application) that is called by the Data Distribution Service when the liveliness ofone or more DDS_DataWriter objects that were writing instances read through thisDDS_DataReader has changed. In other words, some DDS_DataWriter havebecome “alive” or “not alive”. The implementation may be left empty when thisfunctionality is not needed. This operation will only be called when the relevantDDS_DataReaderListener i s i n s t a l l e d a n d e n a b le d f o r t h eDDS_LIVELINESS_CHANGED_STATUS.The Data Distribution Service will provide a pointer to the DDS_DataReader in theparameter reader and the DDS_LivelinessChangedStatus struct for use bythe application.

3.5.6.4 DDS_DataReaderListener_on_requested_deadline_missed (abstract)

Synopsis#include <dds_dcps.h>void DDS_DataReaderListener_on_requested_deadline_missed (void *listener_data, DDS_DataReader reader, const DDS_RequestedDeadlineMissedStatus *status);

DescriptionThis operation must be implemented by the application and is called by the DataDistribution Service when the deadline that the DDS_DataReader was expectingthrough its DDS_DeadlineQosPolicy was not respected.

Parametersinout void *listener_data - a pointer to a user-defined object which may be

used for identification of the Listener.

520API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

in DDS_DataReader reader - contain a pointer to the DDS_DataReader forwhich the deadline was missed (this is an input to the application provided bythe Data Distribution Service).

in const DDS_RequestedDeadlineMissedStatus *status - contain theDDS_RequestedDeadlineMissedStatus struct (this is an input to theapplication provided by the Data Distribution Service).

Return Value<none>

Detailed DescriptionThis operation is the external operation (interface, which must be implemented bythe application) that is called by the Data Distribution Service when the deadlinethat the DDS_DataReader was expecting through its DDS_DeadlineQosPolicywas not respected for a specific instance. The implementation may be left emptywhen this functionality is not needed. This operation will only be called when therelevant DDS_DataReaderListener is installed and enabled for theDDS_REQUESTED_DEADLINE_MISSED_STATUS.The Data Distribution Service will provide a pointer to the DDS_DataReader in theparameter reader and the DDS_RequestedDeadlineMissedStatus structin the parameter status for use by the application.

3.5.6.5 DDS_DataReaderListener_on_requested_incompatible_qos (abstract)

Synopsis#include <dds_dcps.h>void DDS_DataReaderListener_on_requested_incompatible_qos (void *listener_data, DDS_DataReader reader, const DDS_RequestedIncompatibleQosStatus *status);

DescriptionThis operation must be implemented by the application and is called by the DataDistribution Service when the DDS_REQUESTED_INCOMPATIBLE_QOS_STATUSchanges.

Parametersinout void *listener_data - a pointer to a user-defined object which may be

used for identification of the Listener.in DDS_DataReader reader - a pointer to the DDS_DataReader provided by

the Data Distribution Service.

521

API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

in const DDS_RequestedIncompatibleQosStatus *status - theDDS_REQUESTED_INCOMPATIBLE_QOS_STATUS struct provided by the DataDistribution Service.

Return Value<none>

Detailed DescriptionThis operation is the external operation (interface, which must be implemented bythe application) that is called by the Data Distribution Service when theDDS_REQUESTED_INCOMPATIBLE_QOS_STATUS changes. The implementationmay be left empty when this functionality is not needed. This operation will only becalled when the relevant DDS_DataReaderListener is installed and enabled forthe DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS.The Data Distribution Service will provide a pointer to the DDS_DataReader in theparameter reader and the DDS_REQUESTED_INCOMPATIBLE_QOS_STATUSstruct in the parameter status, for use by the application.The application can use this operation as a callback function implementing a properresponse to the status change. This operation is enabled by setting theDDS_REQUESTED_INCOMPATIBLE_QOS_STATUS in the mask in the call toDDS_DataReader_set_listener. When the DDS_DataReaderListener onthe DDS_DataReader i s no t enab l e d fo r t heDDS_REQUESTED_INCOMPATIBLE_QOS_STATUS, the status change will propagateto the DDS_SubscriberListener of the DDS_Subscriber (if enabled) or to theDDS_DomainParticipantListener of the DDS_DomainParticipant (ifenabled).

3.5.6.6 DDS_DataReaderListener_on_sample_lost (abstract)

Synopsis#include <dds_dcps.h>void DDS_DataReaderListener_on_sample_lost (void *listener_data, DDS_DataReader reader, const DDS_SampleLostStatus *status);

NOTE: This operation is not yet implemented. It is scheduled for a future release.

3.5.6.7 DDS_DataReaderListener_on_sample_rejected (abstract)

Synopsis#include <dds_dcps.h>void

522API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

DDS_DataReaderListener_on_sample_rejected (void *listener_data, DDS_DataReader reader, const DDS_SampleRejectedStatus *status);

DescriptionThis operation must be implemented by the application and is called by the DataDistribution Service when a sample has been rejected.

Parametersinout void *listener_data - a pointer to a user-defined object which may be

used for identification of the Listener.in DDS_DataReader reader - contain a pointer to the DDS_DataReader for

which a sample has been rejected (this is an input to the application provided bythe Data Distribution Service).

in const DDS_SampleRejectedStatus *status - conta in theDDS_SampleRejectedStatus struct (this is an input to the applicationprovided by the Data Distribution Service).

Return Value<none>

Detailed DescriptionThis operation is the external operation (interface, which must be implemented bythe application) that is called by the Data Distribution Service when a (received)sample has been rejected. Samples may be rejected by the DDS_DataReader whenit runs out of resource_limits to store incoming samples. Ususally this meansthat old samples need to be ‘consumed’ (for example by ‘taking’ them instead of‘reading’ them) to make room for newly incoming samples.The implementation may be left empty when this functionality is not needed. Thisoperation will only be called when the relevant DDS_DataReaderListener isinstalled and enabled for the DDS_SAMPLE_REJECTED_STATUS.The Data Distribution Service will provide a pointer to the DDS_DataReader in theparameter reader and the DDS_SampleRejectedStatus struct in the parameterstatus for use by the application.

3.5.6.8 DDS_DataReaderListener_on_subscription_matched (abstract)

Synopsis#include <dds_dcps.h>void DDS_DataReaderListener_on_subscription_matched

523API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

(void *listener_data, DDS_DataReader reader, const DDS_SubscriptionMatchedStatus *status);

DescriptionThis operation must be implemented by the application and is called by the DataDistribution Service when a new match has been discovered for the currentsubscription, or when an existing match has ceased to exist.

Parametersinout void *listener_data - a pointer to a user-defined object which may be

used for identification of the Listener.in DDS_DataReader reader - contains a pointer to the DDS_DataReader for

which a match has been discovered (this is an input to the application providedby the Data Distribution Service).

in const SubscriptionMatchedStatus *status - contains theSubscriptionMatchedStatus struct (this is an input to the applicationprovided by the Data Distribution Service).

Return Value<none>

Detailed DescriptionThis operation must be implemented by the application and is called by the DataDistribution Service when a new match has been discovered for the currentsubscription, or when an existing match has ceased to exist. Usually this means thata new DataWriter that matches the Topic and that has compatible Qos as the currentDDS_DataReader has either been discovered, or that a previously discoveredDataWriter has ceased to be matched to the current DDS_DataReader. ADataWriter may cease to match when it gets deleted, when it changes its Qos to avalue that is incompatible with the current DDS_DataReader or when either theDDS_DataReader or the DataWriter has chosen to put its matching counterpart onits ignore-list using the DDS_DomainParticipant_ignore_publication orDDS_DomainParticipant_ignore_subcription operations. The implementation of this Listener operation may be left empty when thisfunctionali ty is not needed: i t wil l only be cal led when the relevantDDS_DataReaderListener i s i n s t a l l e d a n d e n a b le d f o r t h eDDS_SUBSCRIPTION_MATCHED_STATUS.The Data Distribution Service will provide a pointer to the DDS_DataReader in theparameter reader and the DDS_SubscriptionMatchedStatus struct in theparameter status for use by the application.

524API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

3.5.7 Class DDS_ReadConditionThe DDS_DataReader objects can create a set of DDS_ReadCondition (andDDS_StatusCondition) objects which provide support (in conjunction withDDS_WaitSet objects) for an alternative communication style between the DataDistribution Service and the application ( i .e. , wait-based rather thannotification-based).DDS_ReadCondition objects allow an DDS_DataReader to specify the datasamples it is interested in (by specifying the desired sample-states, view-states, andinstance-states); see the parameter definitions for DDS_DataReader'sDDS_DataReader_create_readcondition operation. This allows the DataDistribution Service to trigger the condition only when suitable information isavailable. DDS_ReadCondition objects are to be used in conjunction with aDDS_WaitSet. More than one DDS_ReadCondition may be attached to the sameDDS_DataReader.The interface description of this class is as follows:

/* * interface DDS_ReadCondition *//* * inherited from DDS_Condition *//* DDS_boolean * DDS_ReadCondition_get_trigger_value * (DDS_ReadCondition _this); *//* * implemented API operations */

DDS_SampleStateMask DDS_ReadCondition_get_sample_state_mask (DDS_ReadCondition _this);

DDS_ViewStateMask DDS_ReadCondition_get_view_state_mask (DDS_ReadCondition _this);

DDS_InstanceStateMask DDS_ReadCondition_get_instance_state_mask (DDS_ReadCondition _this);

DDS_DataReader DDS_ReadCondition_get_datareader (DDS_ReadCondition _this);

525API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

The next paragraphs describe the usage of all DDS_ReadCondition operations.The inherited operations are listed but not fully described because they are notimplemented in this class. The full description of these operations is given in theclasses from which they are inherited.

3.5.7.1 DDS_ReadCondition_get_datareader

Synopsis#include <dds_dcps.h>DDS_DataReader DDS_ReadCondition_get_datareader (DDS_ReadCondition _this);

DescriptionThi s ope ra t i on r e tu rns t he DDS_DataReader a s soc i a t ed w i th t heDDS_ReadCondition.

Parametersin DDS_ReadCondition _this - the DDS_ReadCondition object on which

the operation is operated.

Return ValueDDS_DataReader - Result value is a pointer to the DDS_DataReader.

Detailed DescriptionThi s ope ra t i on r e tu rns t he DDS_DataReader a s soc i a t ed w i th t heDDS_ReadCondition. Note that there is exactly one DDS_DataReader associatedwith each DDS_ReadCondition (i.e. the DDS_DataReader that created theDDS_ReadCondition object).

3.5.7.2 DDS_ReadCondition_get_instance_state_mask

Synopsis#include <dds_dcps.h>DDS_InstanceStateMask DDS_ReadCondition_get_instance_state_mask (DDS_ReadCondition _this);

DescriptionThis operation returns the set of instance_states that are taken into account todetermine the trigger_value of the DDS_ReadCondition.

526API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Parametersin DDS_ReadCondition _this - the DDS_ReadCondition object on which

the operation is operated.

Return ValueDDS_InstanceStateMask - Result value are the instance_states specified

when the DDS_ReadCondition was created.

Detailed DescriptionThis operation returns the set of instance_states that are taken into account todetermine the trigger_value of the DDS_ReadCondition.The instance_states returned are the instance_states specified when theDDS_ReadCondition was c r ea t e d . instance_states c an b eDDS_ALIVE_INSTANCE_STATE ,DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE ,DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE or a combination of these.

3.5.7.3 DDS_ReadCondition_get_sample_state_mask

Synopsis#include <dds_dcps.h>DDS_SampleStateMask DDS_ReadCondition_get_sample_state_mask (DDS_ReadCondition _this);

DescriptionThis operation returns the set of sample_states that are taken into account todetermine the trigger_value of the DDS_ReadCondition.

Parametersin DDS_ReadCondition _this - the DDS_ReadCondition object on which

the operation is operated.

Return ValueDDS_SampleStateMask - Result value are the sample_states specified when

the DDS_ReadCondition was created.

Detailed DescriptionThis operation returns the set of sample_states that are taken into account todetermine the trigger_value of the DDS_ReadCondition.

527API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

The sample_states returned are the sample_states specified when theDDS_ReadCondition was c r ea t e d . sample_states c an b eDDS_READ_SAMPLE_STATE, DDS_NOT_READ_SAMPLE_STATE or both.

3.5.7.4 DDS_ReadCondition_get_trigger_value (inherited)This operation is inherited and therefore not described here. See the classDDS_Condition for further explanation.

Synopsis#include <dds_dcps.h>DDS_boolean DDS_ReadCondition_get_trigger_value (DDS_ReadCondition _this);

3.5.7.5 DDS_ReadCondition_get_view_state_mask

Synopsis#include <dds_dcps.h>DDS_ViewStateMask DDS_ReadCondition_get_view_state_mask (DDS_ReadCondition _this);

DescriptionThis operation returns the set of view_states that are taken into account todetermine the trigger_value of the DDS_ReadCondition.

Parametersin DDS_ReadCondition _this - the DDS_ReadCondition object on which

the operation is operated.

Return ValueDDS_ViewStateMask - Result value are the view_states specified when the

DDS_ReadCondition was created.

Detailed DescriptionThis operation returns the set of view_states that are taken into account todetermine the trigger_value of the DDS_ReadCondition.The view_states returned are the view_states specified when theDDS_ReadCondition was c re a t ed . view_states c a n b eDDS_NEW_VIEW_STATE, DDS_NOT_NEW_VIEW_STATE or both.

528API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

3.5.8 Class DDS_QueryConditionDDS_QueryCondition objects are specialized DDS_ReadCondition objects thatallow the application to specify a filter on the locally available data. TheDDS_DataReader objects accept a set of DDS_QueryCondition objects for theDDS_DataReader and provide support (in conjunction with DDS_WaitSetobjects) for an alternative communication style between the Data DistributionService and the application (i.e., wait-based rather than notification-based).

Query FunctionDDS_QueryCondition objects allow an application to specify the data samples itis interested in (by specifying the desired sample-states, view-states, instance-statesand query expression); see the parameter definitions for DDS_DataReader'sDDS_DataReader_read/DDS_DataReader_take operations. This allows theData Distribution Service to trigger the condition only when suitable information isavailable. DDS_QueryCondition objects are to be used in conjunction with aDDS_WaitSet. More than one DDS_QueryCondition may be attached to thesame DDS_DataReader.The query (query_expression) is similar to an SQL WHERE clause and can beparameterized by arguments that are dynamically changeable with theDDS_QueryCondition_set_query_parameters operation.The interface description of this class is as follows:

/* * interface DDS_QueryCondition *//* * inherited from DDS_ReadCondition *//* DDS_SampleStateMask * DDS_QueryCondition_get_sample_state_mask * (DDS_QueryCondition _this);

*//* DDS_ViewStateMask * DDS_QueryCondition_get_view_state_mask * (DDS_QueryCondition _this); */

/* DDS_InstanceStateMask * DDS_QueryCondition_get_instance_state_mask * (DDS_QueryCondition _this); */

/* DDS_DataReader * DDS_QueryCondition_get_datareader * (DDS_QueryCondition _this);

529API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

*//* DDS_boolean * DDS_QueryCondition_get_trigger_value * (DDS_QueryCondition _this); *//* * implemented API operations */

DDS_string DDS_QueryCondition_get_query_expression (DDS_QueryCondition _this);

DDS_ReturnCode_t DDS_QueryCondition_get_query_parameters (DDS_QueryCondition _this, DDS_StringSeq *query_parameters);

DDS_ReturnCode_t DDS_QueryCondition_set_query_parameters (DDS_QueryCondition _this, const DDS_StringSeq *query_parameters);

The next paragraphs describe the usage of all DDS_QueryCondition operations.The inherited operations are listed but not fully described because they are notimplemented in this class. The full description of these operations is given in theclasses from which they are inherited.

3.5.8.1 DDS_QueryCondition_get_datareader (inherited)This operation is inherited and therefore not described here. See the classDDS_ReadCondition for further explanation.

Synopsis#include <dds_dcps.h>DDS_DataReader DDS_QueryCondition_get_datareader (DDS_QueryCondition _this);

3.5.8.2 DDS_QueryCondition_get_instance_state_mask (inherited)This operation is inherited and therefore not described here. See the classDDS_ReadCondition for further explanation.

Synopsis#include <dds_dcps.h>DDS_InstanceStateMask DDS_QueryCondition_get_instance_state_mask (DDS_QueryCondition _this);

530API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

3.5.8.3 DDS_QueryCondition_get_query_parameters

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_QueryCondition_get_query_parameters (DDS_QueryCondition _this, DDS_StringSeq *query_parameters);

DescriptionThis operat ion re turns the query_parameters associated with theDDS_QueryCondition.

Parametersin DDS_QueryCondition _this - the DDS_QueryCondition object on which

the operation is operated.inout DDS_StringSeq *query_parameters - a handle to a sequence of

strings that will be used to store the parameters used in the SQL expression.

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operat ion obtains the query_parameters associated with theDDS_QueryCondition. That is, the parameters specified on the last successful callt o DDS_QueryCondition_set_query_parameters o r, i fDDS_QueryCondition_set_query_parameters was never called, thearguments specified when the DDS_QueryCondition were created. The resultinghandle contains a sequence of strings with the parameters used in the SQLexpression (i.e., the %n tokens in the expression). The number of parameters in theresult sequence will exactly match the number of %n tokens in the query expressionassociated with the DDS_QueryCondition.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the existing set of query parameters applied to thisDDS_QueryCondition has successfully been copied into the specifiedquery_parameters parameter.

531API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_ALREADY_DELETED - the DDS_QueryCondition has already

been deleted.• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out of

resources to complete this operation.

3.5.8.4 DDS_QueryCondition_get_query_expression

Synopsis#include <dds_dcps.h>DDS_string DDS_QueryCondition_get_query_expression (DDS_QueryCondition _this);

DescriptionT h i s o p e r a t i o n r e t u r n s t h e q u e r y e x p r e s s i o n a s s o c i a t e d w i t h t h eDDS_QueryCondition.

Parametersin DDS_QueryCondition _this - the DDS_QueryCondition object on which

the operation is operated.

Return ValueDDS_string - Result value is a pointer to the query expression associated with the

DDS_QueryCondition.

Detailed DescriptionT h i s o p e r a t i o n r e t u r n s t h e q u e r y e x p r e s s i o n a s s o c i a t e d w i t h t h eDDS_QueryCondition . That i s , the express ion speci f ied when theDDS_QueryCondition was created. The operation will return DDS_OBJECT_NILwhen there was an internal error or when the DDS_QueryCondition was alreadydeleted. If there were no parameters, an empty sequence is returned.It is the applications responsibility to free the allocated memory for theDDS_StringSeq.

3.5.8.5 DDS_QueryCondition_get_sample_state_mask (inherited)This operation is inherited and therefore not described here. See the classDDS_ReadCondition for further explanation.

532API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Synopsis#include <dds_dcps.h>DDS_SampleStateMask DDS_QueryCondition_get_sample_state_mask (DDS_QueryCondition _this);

3.5.8.6 DDS_QueryCondition_get_trigger_value (inherited)This operation is inherited and therefore not described here. See the classDDS_ReadCondition for further explanation.

Synopsis#include <dds_dcps.h>DDS_boolean DDS_QueryCondition_get_trigger_value (DDS_QueryCondition _this);

3.5.8.7 DDS_QueryCondition_get_view_state_mask (inherited)This operation is inherited and therefore not described here. See the classDDS_ReadCondition for further explanation.

Synopsis#include <dds_dcps.h>DDS_ViewStateMask DDS_QueryCondition_get_view_state_mask (DDS_QueryCondition _this);

3.5.8.8 DDS_QueryCondition_set_query_parameters

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_QueryCondition_set_query_parameters (DDS_QueryCondition _this, const DDS_StringSeq *query_parameters);

DescriptionThi s ope ra t i on changes t he que ry pa ramete r s a s soc i a t ed w i th t heDDS_QueryCondition.

Parametersin DDS_QueryCondition _this - the DDS_QueryCondition object on which

the operation is operated.

533API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

in const DDS_StringSeq *query_parameters - a sequence of strings whichare the parameters used in the SQL query string (i.e., the “%n” tokens in theexpression).

Return ValueDDS_ReturnCode_t - Poss ib le re tu rn codes o f the opera t ion a re :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThi s ope ra t i on changes t he que ry pa ramete r s a s soc i a t ed w i th t heDDS_QueryCondition. The parameter query_parameters is a sequence ofstrings which are the parameters values used in the SQL query string (i.e., the “%n”tokens in the expression). The number of values in query_parameters must beequal or greater than the highest referenced %n token in the query_expression(e.g. if %1 and %8 are used as parameter in the query_expression, thequery_parameters should at least contain n+1 = 9 values).

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the query parameters associated with theDDS_QueryCondition are changed.

• DDS_RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• DDS_RETCODE_BAD_PARAMETER - the number of parameters inquery_parameters does not match the number of “%n” tokens in theexpression for this DDS_QueryCondition or one of the parameters is an illegalparameter.

• DDS_RETCODE_ALREADY_DELETED - the DDS_QueryCondition has alreadybeen deleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

3.5.9 Class DDS_DataReaderView (abstract)A DataReaderView allows the application to create an additional view on the datasetstored in a DataReader. The view is expressed by an (optional) alternative key listspecified in the DDS_DataReaderViewQos, which allows it to specify analternative storage spectrum. Applications might prefer such an alternative storage

534API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

spectrum (for example by adding or removing key-fields) because it may help themto process the samples in a different order/cohesion than what they will have whenthey use the original key-list.A DataReaderView has the following properties:• Any DDS_DataReaderView belongs to exactly one DDS_DataReader.• A DDS_DataReader can have zero to many DDS_DataReaderViews attached

(all with their own key_list definitions).• The DDS_DataReaderView has the same interface as the DDS_DataReader

with its read and take variants, including w_condition and next_instance,next_sample, etc. It also supports DDS_ReadConditions andDDS_QueryConditions like a DDS_DataReader does.

• Any sample that is inserted into the DataReader will introduce a correspondingDataViewSample in all its attached DataReaderViews in a ViewInstance asdefined by the keys specified in the DataReaderView Qos key_list when theview was created.

• Like samples in a DataReader, DataViewSamples in a DataReaderView belong toexactly one ViewInstance. Instances in the dataReaderView do not have anyinstance state information though. The instance state information found in theSampleInfo for each DataReaderView sample is copied from the correspondingDataReader sample.

• Whenever a sample is taken from the DataReader, its corresponding samples in allattached DataReaderViews will be removed as well. The same goes for samplesthat are pushed out of the DataReader instance history (in case of a KEEP_LASTHistoryQosPolicy) or for samples whose lifespan expired.

• A ViewInstance always has an infinite history depth; samples can not be pushedout of the view.

• Whenever a sample is taken from a DataReaderView, it is removed from thatDataReaderView but not from the DataReader, nor from any of its other views. Ifall samples in a ViewInstance are taken, then that ViewInstance is destroyed.

DDS_DataReaderView is an abstract class. It is specialized for each particularapplication data type. For a fictional application data type "Foo" (defined in themodule SPACE) the specialized class would be SPACE_FooDataReaderView.The interface description of this class is as follows:

/* * interface DDS_DataReaderView *//* * inherited from class DDS_Entity */

535API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

/* DDS_StatusCondition * DDS_DataReaderView_get_statuscondition * (DDS_DataReaderView _this); *//* * DDS_StatusMask * DDS_DataReaderView_get_status_changes * (DDS_DataReaderView _this); *//* * DDS_ReturnCode_t * DDS_DataReaderView_enable * (DDS_DataReaderView _this); *//* * abstract operations * (implemented in the data type specific DDS_DataReaderView) *//* * DDS_ReturnCode_t * DDS_DataReaderView_get_key_value * (DDS_DataReaderView _this, * <data> *key_holder, * const DDS_InstanceHandle_t handle); *//*/* DDS_InstanceHandle_t * DDS_DataReaderView_lookup_instance * (DDS_DataReaderView _this, * const <data> *instance_data); *//* * DDS_ReturnCode_t * DDS_DataReaderView_read * (DDS_DataReaderView _this, * DDS_sequence_<data> *data_values, * SampleInfoSeq *info_seq, * const DDS_long max_samples, * const DDS_SampleStateMask sample_states, * const DDS_ViewStateMask view_states, * const DDS_InstanceStateMask instance_states); *//* * DDS_ReturnCode_t * DDS_DataReaderView_read_instance * (DDS_DataReaderView _this, * DDS_sequence_<data> *data_values, * SampleInfoSeq *info_seq, * const DDS_long max_samples, * const DDS_InstanceHandle_t a_handle,

536API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

* const DDS_SampleStateMask sample_states, * const DDS_ViewStateMask view_states, * const DDS_InstanceStateMask instance_states); *//* * DDS_ReturnCode_t * DDS_DataReaderView_read_next_instance * (DDS_DataReaderView _this, * DDS_sequence_<data> *data_values, * SampleInfoSeq *info_seq, * const DDS_long max_samples, * const DDS_InstanceHandle_t a_handle, * const DDS_SampleStateMask sample_states, * const DDS_ViewStateMask view_states, * const DDS_InstanceStateMask instance_states); *//* * DDS_ReturnCode_t * DDS_DataReaderView_read_next_instance_w_condition * (DDS_DataReaderView _this, * DDS_sequence_<data> *data_values, * SampleInfoSeq *info_seq, * const DDS_long max_samples, * const DDS_InstanceHandle_t a_handle, * const DDS_ReadCondition a_condition); *//* * DDS_ReturnCode_t * DDS_DataReaderView_read_next_sample * (DDS_DataReaderView _this, * <data> *received_data, * DDS_SampleInfo *sample_info); *//* * DDS_ReturnCode_t * DDS_DataReaderView_read_w_condition * (DDS_DataReaderView _this, * DDS_sequence_<data> *data_values, * SampleInfoSeq *info_seq, * const DDS_long max_samples, * const DDS_ReadCondition a_condition); *//* * DDS_ReturnCode_t * DDS_DataReaderView_return_loan * (DDS_DataReaderView _this, * DDS_sequence_<data> *data_values, * SampleInfoSeq *info_seq); *//*

537API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

* DDS_ReturnCode_t * DDS_DataReaderView_take * (DDS_DataReaderView _this, * DDS_sequence_<data> *data_values, * SampleInfoSeq *info_seq, * const DDS_long max_samples, * const DDS_SampleStateMask sample_states, * const DDS_ViewStateMask view_states, * const DDS_InstanceStateMask instance_states); *//* * DDS_ReturnCode_t * DDS_DataReaderView_take_instance * (DDS_DataReaderView _this, * DDS_sequence_<data> *data_values, * SampleInfoSeq *info_seq, * const DDS_long max_samples, * const DDS_InstanceHandle_t a_handle, * const DDS_SampleStateMask sample_states, * const DDS_ViewStateMask view_states, * const DDS_InstanceStateMask instance_states); *//* * DDS_ReturnCode_t * DDS_DataReaderView_take_next_instance * (DDS_DataReaderView _this, * DDS_sequence_<data> *data_values, * SampleInfoSeq *info_seq, * const DDS_long max_samples, * const DDS_InstanceHandle_t a_handle, * const DDS_SampleStateMask sample_states, * const DDS_ViewStateMask view_states, * const DDS_InstanceStateMask instance_states); *//* * DDS_ReturnCode_t * DDS_DataReaderView_take_next_instance_w_condition * (DDS_DataReaderView _this, * DDS_sequence_<data> *data_values, * SampleInfoSeq *info_seq, * const DDS_long max_samples, * const DDS_InstanceHandle_t a_handle, * const DDS_ReadCondition a_condition); *//* * DDS_ReturnCode_t * DDS_DataReaderView_take_next_sample * (DDS_DataReaderView _this, * <data> *received_data, * DDS_SampleInfo *sample_info);

538API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

*//* * DDS_ReturnCode_t * DDS_DataReaderView_take_w_condition * (DDS_DataReaderView _this, * DDS_sequence_<data> *data_values, * SampleInfoSeq *info_seq, * const DDS_long max_samples, * const DDS_ReadCondition a_condition); *//* * implemented API operations */

DDS_QueryCondition DDS_DataReaderView_create_querycondition (DDS_DataReaderView _this, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states, const DDS_char *query_expression, const DDS_StringSeq *query_parameters);

DDS_ReadCondition DDS_DataReaderView_create_readcondition (DDS_DataReaderView _this, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

DDS_ReturnCode_t DDS_DataReaderView_delete_contained_entities (DDS_DataReaderView _this);

DDS_ReturnCode_t DDS_DataReaderView_delete_readcondition (DDS_DataReaderView _this, const DDS_ReadCondition a_condition);

DDS_DataReader DDS_DataReaderView_get_datareader (DDS_DataReaderView _this);

DDS_ReturnCode_t DDS_DataReaderView_get_qos (DDS_DataReaderView _this, DDS_DataReaderViewQos *qos);

DDS_ReturnCode_t DDS_DataReaderView_set_qos

539API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

(DDS_DataReaderView _this, const DDS_DataReaderViewQos *qos);

The next paragraphs describe the usage of all DataReaderView operations. Theinherited and abstract operations are listed but not fully described because they arenot implemented in this class. The full description of these operations is given in theclasses from which they are inherited and in the data type specific classes in whichthey are implemented.Because the DataReaderView closely follows DataReader semantics, a lot ofoperations are identical. In those cases where the operation on the DataReaderViewis identical to the one on the DataReader, no full description is given but theoperation on the DataReader or its respective type specific class is referenced.

3.5.9.1 DDS_DataReaderView_create_querycondition

Synopsis#include <dds_dcps.h>DDS_QueryCondition DDS_DataReaderView_create_querycondition (DDS_DataReaderView _this, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states, const DDS_char *query_expression, const DDS_StringSeq *query_parameters);

DescriptionThis operation creates a new QueryCondition for the DataReaderView. For a fulld e s c r i p t i o n p l e a s e r e f e r t o S e c t i o n 3 . 5 . 2 . 2 ,DDS_DataReader_create_querycondition, on page 427, which describes thisoperation in detail for the DataReader class.

3.5.9.2 DDS_DataReaderView_create_readcondition

Synopsis#include <dds_dcps.h>DDS_ReadCondition DDS_DataReaderView_create_readcondition (DDS_DataReaderView _this, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

540API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

DescriptionThis operation creates a new ReadCondition for the DataReaderView. For a fulldescription please refer to Section 3.5.2.3, DDS_DataReader_create_readcondition,on page 428, which describes this operation in detail for the DataReader class.

3.5.9.3 DDS_DataReaderView_delete_contained_entities

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReaderView_delete_contained_entities (DDS_DataReaderView _this);

DescriptionThis operation deletes all the entities that were created by means of one of the"create_" operations on the DataReaderView. For a full description please refer toSection 3.5.2.5, DDS_DataReader_delete_contained_entities, on page 430, whichdescribes this operation in detail for the DataReader class.

3.5.9.4 DDS_DataReaderView_delete_readcondition

Synopsis#include <dds_dcps.h>

DDS_ReturnCode_t DDS_DataReaderView_delete_readcondition (DDS_DataReaderView _this, DDS_ReadCondition a_condition);

DescriptionThis operation deletes a ReadCondition or QueryCondition which is attached to theDataReaderView. For a full description please refer to Section 3.5.2.5,DDS_DataReader_delete_contained_entities, on page 430, which describes thisoperation in detail for the DataReader class.

3.5.9.5 DDS_DataReaderView_enable (inherited)This operation is inherited and therefore not described here. See the class Entity forfurther explanation.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReaderView_enable (DDS_DataReaderView _this);

541API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

3.5.9.6 DDS_DataReaderView_get_datareader

Synopsis#include <dds_dcps.h>DDS_DataReader DDS_DataReaderView_get_datareader (DDS_DataReaderView _this);

DescriptionRetrieves the DataReader to which this DataReaderView is attached.

Parametersin DDS_DataReaderView - the DDS_DataReaderView object on which the

operation is operated.

Return ValueDDS_DataReader - Return value is a pointer to the DDS_DataReader to which

the DDS_DataReaderView belongs.

Detailed DescriptionThis operation returns a pointer to the DDS_DataReader from which theDDS_DataReaderView was originally created. If the DDS_DataReaderView isalready deleted, the DDS_OBJECT_NIL pointer is returned.

3.5.9.7 DDS_DataReaderView_get_key_value (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReaderView class. Therefore, to use thisoperation, the data type specific implementation of this operation in its respectivederived class must be used. For further explanation see the description for thef i c t i o na l da t a t y pe Foo ( d e f in e d i n t h e m o d u l e SPACE ) d e r i v e dSPACE_FooDataReaderView class.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReaderView_get_key_value (DDS_DataReaderView _this, <data> *key_holder, const DDS_InstanceHandle_t handle);

542API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

3.5.9.8 DDS_DataReaderView_get_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReaderView_get_qos (DDS_DataReaderView _this, DDS_DataReaderViewQos *qos);

DescriptionThis operation al lows access to the exist ing set of QoS policies of aDDS_DataReaderView o n w h ic h t h i s o p e r a t i o n i s u s e d . T h i sDDS_DataReaderViewQos is stored at the location pointed to by the qosparameter.

Parametersin DDS_DataReaderView - the DDS_DataReaderView object on which the

operation is operated.inout DataReaderViewQos *qos - a poin ter to the des t ina t ion

DDS_DataReaderViewQos struct in which the QosPolicy settings will becopied.

Return ValueDDS_ReturnCode_t - Poss ib le re turn codes of the opera t ion are :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION, DDS_RETCODE_ALREADY_DELETED or DDS_RETCODE_OUT_OF_RESOURCES.

Detailed DescriptionThis operation al lows access to the exist ing set of QoS policies of aDDS_DataReaderView o n w h ic h t h i s o p e r a t i o n i s u s e d . T h i sDDS_DataReaderViewQos is stored at the location pointed to by the qosparameter.

Return CodeWhen the operation returns:• DDS_RETCODE_OK - the existing set of QoSPolicy values applied to thisDDS_DataReaderView has successfully been copied into the specifiedDDS_DataReaderViewQos parameter.

• DDS_RETCODE_ERROR - an internal error has occurred.

543API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on aninappropriate object.

• DDS_RETCODE_ALREADY_DELETED - the DDS_DataReaderView has alreadybeen deleted.

• DDS_RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

3.5.9.9 DDS_DataReaderView_get_status_changes (inherited)This operation is inherited and therefore not described here. See the class Entity forfurther explanation.

Synopsis#include <dds_dcps.h>DDS_StatusMask DDS_DataReaderView_get_status_changes (DDS_DataReaderView _this);

3.5.9.10 DDS_DataReaderView_get_statuscondition (inherited)This operation is inherited and therefore not described here. See the class Entity forfurther explanation.

Synopsis#include <dds_dcps.h>DDS_StatusCondition DDS_DataReaderView_get_statuscondition (DDS_DataReaderView _this);

3.5.9.11 DDS_DataReaderView_lookup_instance (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReaderView class. Therefore, to use thisoperation, the data type specific implementation of this operation in its respectivederived class must be used. For further explanation see the description for thef i c t i o na l da t a t y pe Foo ( d e f in e d i n t h e m o d u l e SPACE ) d e r i v e dSPACE_FooDataReaderView class.

Synopsis#include <dds_dcps.h>DDS_InstanceHandle_t DDS_DataReaderView_lookup_instance (DDS_DataReaderView _this, const <data> *instance_data);

544API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

3.5.9.12 DDS_DataReaderView_read (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReaderView class. Therefore, to use thisoperation, the data type specific implementation of this operation in its respectivederived class must be used. For further explanation see the description for thef i c t i o na l da t a t y pe Foo ( d e f in e d i n t h e m o d u l e SPACE ) d e r i v e dSPACE_FooDataReaderView class.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReaderView_read (DDS_DataReaderView _this, DDS_sequence_<data> *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

3.5.9.13 DDS_DataReaderView_read_instance (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReaderView class. Therefore, to use thisoperation, the data type specific implementation of this operation in its respectivederived class must be used. For further explanation see the description for thef i c t i o na l da t a t y pe Foo ( d e f in e d i n t h e m o d u l e SPACE ) d e r i v e dSPACE_FooDataReaderView class.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReaderView_read_instance (DDS_DataReaderView _this, DDS_sequence_<data> *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

3.5.9.14 DDS_DataReaderView_read_next_instance (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReaderView class. Therefore, to use thisoperation, the data type specific implementation of this operation in its respective

545API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

derived class must be used. For further explanation see the description for thef i c t i o na l da t a t y pe Foo ( d e f in e d i n t h e m o d u l e SPACE ) d e r i v e dSPACE_FooDataReaderView class.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReaderView_read_next_instance (DDS_DataReaderView _this, DDS_sequence_<data> *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

3.5.9.15 DDS_DataReaderView_read_next_instance_w_condition (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReaderView class. Therefore, to use thisoperation, the data type specific implementation of this operation in its respectivederived class must be used. For further explanation see the description for thef i c t i o na l da t a t y pe Foo ( d e f in e d i n t h e m o d u l e SPACE ) d e r i v e dSPACE_FooDataReaderView class.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReaderView_read_next_instance_w_condition (DDS_DataReaderView _this, DDS_sequence_<data> *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_ReadCondition a_condition);

3.5.9.16 DDS_DataReaderView_read_next_sample (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReaderView class. Therefore, to use thisoperation, the data type specific implementation of this operation in its respectivederived class must be used. For further explanation see the description for thef i c t i o na l da t a t y pe Foo ( d e f in e d i n t h e m o d u l e SPACE ) d e r i v e dSPACE_FooDataReaderView class.

546API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReaderView_read_next_sample (DDS_DataReaderView _this, <data> *data_values, DDS_SampleInfo *sample_info);

3.5.9.17 DDS_DataReaderView_read_w_condition (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReaderView class. Therefore, to use thisoperation, the data type specific implementation of this operation in its respectivederived class must be used. For further explanation see the description for thef i c t i o na l da t a t y pe Foo ( d e f in e d i n t h e m o d u l e SPACE ) d e r i v e dSPACE_FooDataReaderView class.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReaderView_read_w_condition (DDS_DataReaderView _this, DDS_sequence_<data> *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_ReadCondition a_condition);

3.5.9.18 DDS_DataReaderView_return_loan (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReaderView class. Therefore, to use thisoperation, the data type specific implementation of this operation in its respectivederived class must be used. For further explanation see the description for thef i c t i o na l da t a t y pe Foo ( d e f in e d i n t h e m o d u l e SPACE ) d e r i v e dSPACE_FooDataReaderView class.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReaderView_return_loan (DDS_DataReaderView _this, DDS_sequence_<data> *data_values, SampleInfoSeq *info_seq);

547API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

3.5.9.19 DDS_DataReaderView_set_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReaderView_set_qos (DDS_DataReaderView _this, const DDS_DataReaderViewQos *qos);

DescriptionThis operat ion replaces the exis t ing set of QosPol icy set t ings for aDDS_DataReaderView.

Parametersin DDS_DataReaderView - the DDS_DataReaderView object on which the

operation is operated.in const DDS_DataReaderViewQos *qos - the new set of QosPolicy settings

for the DDS_DataReaderView.

Return ValueDDS_ReturnCode_t - Poss ib le re turn codes of the opera t ion are :

DDS_RETCODE_OK, DDS_RETCODE_ERROR, DDS_RETCODE_ILLEGAL_OPERATION , DDS_RETCODE_BAD_PARAMETER , DDS_RETCODE_ALREADY_DELETED, DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_IMMUTABLE_POLICY.

Detailed DescriptionThis operat ion replaces the exis t ing set of QosPol icy set t ings for aDDS_DataReaderView.The parameter qos contains the QosPolicy settings which is checked forself-consistency and mutability. When the application tries to change a QosPolicysetting for an enabled DDS_DataReaderView, which can only be set before theDDS_DataReaderView i s e n a b l e d , t h e o p e r a t i o n w i l l f a i l a n d aDDS_RETCODE_IMMUTABLE_POLICY is returned. In other words, the applicationmust provide the presently set QosPolicy settings in case of the immutableQosPolicy settings. Only the mutable QosPolicy settings can be changed. The set of QosPolicy settings specified by the qos parameter are applied on top ofthe existing QoS, replacing the values of any policies previously set (provided thatthe operation returned DDS_RETCODE_OK).

548API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Return CodeWhen the operation returns:• RETCODE_OK - the new DataReaderViewQos is set.• RETCODE_ERROR - an internal error has occurred.• DDS_RETCODE_ILLEGAL_OPERATION - the operation is invoked on an

inappropriate object.• RETCODE_BAD_PARAMETER - the parameter qos is not a validDataReaderViewQos. It contains NULL pointer strings or strings that do notrepresent accessible attributes of the datatype.

• RETCODE_ALREADY_DELETED - the DDS_DataReaderView has already beendeleted.

• RETCODE_OUT_OF_RESOURCES - the Data Distribution Service ran out ofresources to complete this operation.

• RETCODE_IMMUTABLE_POLICY - the parameter qos contains an immutableQosPolicy setting with a value different from the one set during enabling of theDataReader.

3.5.9.20 DDS_DataReaderView_take (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReaderView class. Therefore, to use thisoperation, the data type specific implementation of this operation in its respectivederived class must be used. For further explanation see the description for thef i c t i o na l da t a t y pe Foo ( d e f in e d i n t h e m o d u l e SPACE ) d e r i v e dSPACE_FooDataReaderView class.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReaderView_take (DDS_DataReaderView _this, DDS_sequence_<data> *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

3.5.9.21 DDS_DataReaderView_take_instance (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReaderView class. Therefore, to use thisoperation, the data type specific implementation of this operation in its respective

549API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

derived class must be used. For further explanation see the description for thef i c t i o na l da t a t y pe Foo ( d e f in e d i n t h e m o d u l e SPACE ) d e r i v e dSPACE_FooDataReaderView class.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReaderView_take_instance (DDS_DataReaderView _this, DDS_sequence_<data> *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

3.5.9.22 DDS_DataReaderView_take_next_instance (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReaderView class. Therefore, to use thisoperation, the data type specific implementation of this operation in its respectivederived class must be used. For further explanation see the description for thef i c t i o na l da t a t y pe Foo ( d e f in e d i n t h e m o d u l e SPACE ) d e r i v e dSPACE_FooDataReaderView class.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReaderView_take_next_instance (DDS_DataReaderView _this, DDS_sequence_<data> *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

3.5.9.23 DDS_DataReaderView_take_next_instance_w_condition (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReaderView class. Therefore, to use thisoperation, the data type specific implementation of this operation in its respectivederived class must be used. For further explanation see the description for thef i c t i o na l da t a t y pe Foo ( d e f in e d i n t h e m o d u l e SPACE ) d e r i v e dSPACE_FooDataReaderView class.

550API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReaderView_take_next_instance_w_condition (DDS_DataReaderView _this, DDS_sequence_<data> *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_ReadCondition a_condition);

3.5.9.24 DDS_DataReaderView_take_next_sample (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReaderView class. Therefore, to use thisoperation, the data type specific implementation of this operation in its respectivederived class must be used. For further explanation see the description for thef i c t i o na l da t a t y pe Foo ( d e f in e d i n t h e m o d u l e SPACE ) d e r i v e dSPACE_FooDataReaderView class.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReaderView_take_next_sample (DDS_DataReaderView _this, <data> *data_values, DDS_SampleInfo *sample_info);

3.5.9.25 DDS_DataReaderView_take_w_condition (abstract)This abstract operation is defined as a generic operation, which is implemented bythe <NameSpace>_<type>DataReaderView class. Therefore, to use thisoperation, the data type specific implementation of this operation in its respectivederived class must be used. For further explanation see the description for thef i c t i o na l da t a t y pe Foo ( d e f in e d i n t h e m o d u l e SPACE ) d e r i v e dSPACE_FooDataReaderView class.

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_DataReaderView_take_w_condition (DDS_DataReaderView _this, DDS_sequence_<data> *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_ReadCondition a_condition);

551API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

3.5.10 Class SPACE_FooDataReaderViewT h e p r e p r o c e s s o r g e n e r a t e s f r o m I D L t y p e d e s c r i p t i o n s t h e<NameSpace>_<type>DataReaderView classes. For each application data typew hi c h i s u s e d a s Top ic d a t a t yp e , a t y ped c l a s s<NameSpace>_<type>DataReaderView i s d e r i v e d f r o m t h eDDS_DataReaderView c l a s s . In t h i s pa r ag r ap h , t he c l a s sSPACE_FooDataReaderView describes the operations of these derived<NameSpace>_<type>DataReaderView classes as an example for the fictionalapplication type Foo (defined in the module SPACE).For instance, for an application, the definitions are located in the Space.idl file.The pre-processor will generate a Space.h include file.The interface description of this class is as follows:

/* * interface SPACE_FooDataReaderView *//* * inherited from class DDS_Entity *//* DDS_StatusCondition * SPACE_FooDataReaderView_get_statuscondition * (SPACE_FooDataReaderView _this); *//* * DDS_StatusMask * SPACE_FooDataReaderView_get_status_changes * (SPACE_FooDataReaderView _this); *//* * DDS_ReturnCode_t * SPACE_FooDataReaderView_enable * (SPACE_FooDataReaderView _this); *//* * inherited from class DDS_DataReaderView *//* * DDS_QueryCondition * SPACE_FooDataReaderView_create_querycondition * (SPACE_FooDataReaderView _this, * const DDS_SampleStateMask sample_states, * const DDS_ViewStateMask view_states, * const DDS_InstanceStateMask instance_states, * const DDS_char *query_expression, * const DDS_StringSeq *query_parameters); *//*

552API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

* DDS_ReadCondition * SPACE_FooDataReaderView_create_readcondition * (SPACE_FooDataReaderView _this, * const DDS_SampleStateMask sample_states, * const DDS_ViewStateMask view_states, * const DDS_InstanceStateMask instance_states); *//* * DDS_ReturnCode_t * SPACE_FooDataReaderView_delete_contained_entities * (SPACE_FooDataReaderView _this); *//* * DDS_ReturnCode_t * SPACE_FooDataReaderView_delete_readcondition * (SPACE_FooDataReaderView _this, * const DDS_ReadCondition a_condition); *//* * DDS_DataReader * SPACE_FooDataReaderView_get_datareader * (SPACE_FooDataReaderView _this); *//* * DDS_ReturnCode_t * SPACE_FooDataReaderView_get_qos * (SPACE_FooDataReaderView _this, * DDS_DataReaderViewQos *qos); *//* * DDS_ReturnCode_t * SPACE_FooDataReaderView_set_qos * (SPACE_FooDataReaderView _this, * const DDS_DataReaderViewQos *qos);

*//* * implemented API operations */ DDS_ReturnCode_t SPACE_FooDataReaderView_get_key_value (SPACE_FooDataReaderView _this, Foo *key_holder, const DDS_InstanceHandle_t handle);

DDS_InstanceHandle_t SPACE_FooDataReaderView_lookup_instance (SPACE_FooDataReaderView _this, const Foo *instance_data);

553API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

DDS_ReturnCode_t SPACE_FooDataReaderView_read (SPACE_FooDataReaderView _this, DDS_sequence_Foo *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

DDS_ReturnCode_t SPACE_FooDataReaderView_read_instance (SPACE_FooDataReaderView _this, DDS_sequence_Foo *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

DDS_ReturnCode_t SPACE_FooDataReaderView_read_next_instance (SPACE_FooDataReaderView _this, DDS_sequence_Foo *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

DDS_ReturnCode_t SPACE_FooDataReaderView_read_next_instance_w_condition (SPACE_FooDataReaderView _this, DDS_sequence_Foo *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_ReadCondition a_condition);

DDS_ReturnCode_t SPACE_FooDataReaderView_read_next_sample (SPACE_FooDataReaderView _this, Foo *received_data, DDS_SampleInfo *sample_info);

DDS_ReturnCode_t SPACE_FooDataReaderView_read_w_condition (SPACE_FooDataReaderView _this,

554API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

DDS_sequence_Foo *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_ReadCondition a_condition);

DDS_ReturnCode_t SPACE_FooDataReaderView_return_loan (SPACE_FooDataReaderView _this, DDS_sequence_Foo *data_values, SampleInfoSeq *info_seq);

DDS_ReturnCode_t SPACE_FooDataReaderView_take (SPACE_FooDataReaderView _this, DDS_sequence_Foo *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

DDS_ReturnCode_t SPACE_FooDataReaderView_take_instance (SPACE_FooDataReaderView _this, DDS_sequence_Foo *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

DDS_ReturnCode_t SPACE_FooDataReaderView_take_next_instance (SPACE_FooDataReaderView _this, DDS_sequence_Foo *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

DDS_ReturnCode_t SPACE_FooDataReaderView_take_next_instance_w_condition (SPACE_FooDataReaderView _this, DDS_sequence_Foo *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle,

555API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

const DDS_ReadCondition a_condition);

DDS_ReturnCode_t SPACE_FooDataReaderView_take_next_sample (SPACE_FooDataReaderView _this, Foo *received_data, DDS_SampleInfo *sample_info);

DDS_ReturnCode_t SPACE_FooDataReaderView_take_w_condition (SPACE_FooDataReaderView _this, DDS_sequence_Foo *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_ReadCondition a_condition);

The next paragraphs describe the usage of all SPACE_FooDataReaderViewoperations. The inherited operations are listed but not fully described because theyare not implemented in this class. The full description of these operations is given inthe classes from which they are inherited.

3.5.10.1 SPACE_FooDataReaderView_create_querycondition (inherited)This operation is inherited and therefore not described here. See the classDDS_DataReaderView for further explanation.

Synopsis#include <Space.h>DDS_QueryCondition SPACE_FooDataReaderView_create_querycondition (SPACE_FooDataReaderView _this, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states, const DDS_char *query_expression, const DDS_StringSeq *query_parameters);

3.5.10.2 SPACE_FooDataReaderView_create_readcondition (inherited)This operation is inherited and therefore not described here. See the classDDS_DataReaderView for further explanation.

Synopsis#include <Space.h>DDS_ReadCondition SPACE_FooDataReaderView_create_readcondition (SPACE_FooDataReaderView _this, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

556API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

3.5.10.3 SPACE_FooDataReaderView_delete_contained_entitiesThis operation is inherited and therefore not described here. See the classDDS_DataReaderView for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReaderView_delete_contained_entities (SPACE_FooDataReaderView _this);

3.5.10.4 SPACE_FooDataReaderView_delete_readcondition (inherited)This operation is inherited and therefore not described here. See the classDDS_DataReaderView for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReaderView_delete_readcondition (SPACE_FooDataReaderView _this, const DDS_ReadCondition a_condition);

3.5.10.5 SPACE_FooDataReaderView_enable (inherited)This operation is inherited and therefore not described here. See the classDDS_Entity for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReaderView_enable (SPACE_FooDataReaderView _this);

3.5.10.6 SPACE_FooDataReaderView_get_datareader (inherited)This operation is inherited and therefore not described here. See the classDDS_DataReaderView for further explanation

Synopsis#include <Space.h>DDS_DataReader SPACE_FooDataReaderView_get_datareader (SPACE_FooDataReaderView _this);

557API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

3.5.10.7 SPACE_FooDataReaderView_get_key_value

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReaderView_get_key_value (SPACE_FooDataReaderView _this, Foo *key_holder, const DDS_InstanceHandle_t handle);

NOTE: This operation is not yet implemented. It is scheduled for a future release.

3.5.10.8 SPACE_FooDataReaderView_get_qos (inherited)This operation is inherited and therefore not described here. See the classDDS_DataReaderView for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReaderView_get_qos (SPACE_FooDataReaderView _this, DDS_DataReaderViewQos *qos);

3.5.10.9 SPACE_FooDataReaderView_get_status_changes (inherited)This operation is inherited and therefore not described here. See the classDDS_Entity for further explanation.

Synopsis#include <Space.h>DDS_StatusMask SPACE_FooDataReaderView_get_status_changes (SPACE_FooDataReaderView _this);

3.5.10.10 SPACE_FooDataReaderView_get_statuscondition (inherited)This operation is inherited and therefore not described here. See the classDDS_Entity for further explanation.

Synopsis#include <Space.h>DDS_StatusCondition SPACE_FooDataReaderView_get_statuscondition (SPACE_FooDataReaderView _this);

558API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

3.5.10.11 SPACE_FooDataReaderView_lookup_instance

Synopsis#include <Space.h>DDS_InstanceHandle_t SPACE_FooDataReaderView_lookup_instance (SPACE_FooDataReaderView _this, const Foo* instance_data)

DescriptionThis operation returns the value of the instance handle which corresponds to theinstance_data. For a full description please refer to paragraph '3.5.2.60look up_ ins t an ce ' wh ich desc r ibe s t h i s o pe ra t i on i n de t a i l f o r t heSPACE_FooDataReader c l a s s . N o t e t h a t i n s t a n c e s i n t h eSPACE_FooDataReaderView a r e no t de f i n ed by t h e k eys o f t h eDDS_TopicDescription but by the key list in the DDS_DataReaderViewQosPolicy.

3.5.10.12 SPACE_FooDataReaderView_read

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReaderView_read (SPACE_FooDataReaderView _this, DDS_sequence_Foo *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

DescriptionT h i s o p e r a t i o n r e a ds a s e q u e n c e o f F o o s a m p l e s f r o m t h eSPACE_FooDataReaderView. For a full description please refer to Section3.5.2.66, SPACE_FooDataReader_read, on page 478, which describes thisoperation in detail for the SPACE_FooDataReader class.

3.5.10.13 SPACE_FooDataReaderView_read_instance

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReaderView_read_instance (SPACE_FooDataReaderView _this,

559API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

DDS_sequence_Foo *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

DescriptionThis operation reads a sequence of Foo samples of a single instance from theSPACE_FooDataReaderView. For a full description please refer to Section3.5.2.67, SPACE_FooDataReader_read_instance, on page 483, which describes thisoperation in detail for the SPACE_FooDataReader class.

3.5.10.14 SPACE_FooDataReaderView_read_next_instance

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReaderView_read_next_instance (SPACE_FooDataReaderView _this, DDS_sequence_Foo *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

DescriptionThis operation reads a sequence of Foo samples of the next single instance from theSPACE_FooDataReaderView. For a full description please refer to Section3.5.2.68, SPACE_FooDataReader_read_next_instance, on page 485, whichdescribes this operation in detail for the SPACE_FooDataReader class.

3.5.10.15 SPACE_FooDataReaderView_read_next_instance_w_condition

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReaderView_read_next_instance_w_condition (SPACE_FooDataReaderView _this, DDS_sequence_Foo *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle,

560API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

const DDS_ReadCondition a_condition);

DescriptionThis operation reads a sequence of Foo samples of the next single instance from theSPACE_FooDataReaderView, f i l tered by a DDS_ReadCondition orDDS_QueryCondition. For a full description please refer to Section 3.5.2.69,SPACE_FooDataReader_read_next_instance_w_condition, on page 488, whichdescribes this operation in detail for the SPACE_FooDataReader class.

3.5.10.16 SPACE_FooDataReaderView_read_next_sample

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReaderView_read_next_sample (SPACE_FooDataReaderView _this, Foo *data_values, DDS_SampleInfo *sample_info);

NOTE: This operation is not yet implemented. It is scheduled for a future release.

3.5.10.17 SPACE_FooDataReaderView_read_w_condition

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReaderView_read_w_condition (SPACE_FooDataReaderView _this, DDS_sequence_Foo *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_ReadCondition a_condition);

DescriptionT h i s o p e r a t i o n r e a ds a s e q u e n c e o f F o o s a m p l e s f r o m t h eSPACE_FooDataReaderView, f i l tered by a DDS_ReadCondition orDDS_QueryCondition. For a full description please refer to Section 3.5.2.71,SPACE_FooDataReader_read_w_condition, on page 490, which describes thisoperation in detail for the SPACE_FooDataReader class.

3.5.10.18 SPACE_FooDataReaderView_return_loan

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReaderView_return_loan

561API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

(SPACE_FooDataReaderView _this, DDS_sequence_Foo *data_values, SampleInfoSeq *info_seq);

DescriptionThis operation indicates to the SPACE_FooDataReaderView that the application isdone accessing the sequence of data_values and info_seq. For a fulldescription please refer to Section 3.5.2.72, SPACE_FooDataReader_return_loan,on pa ge 4 92 , w h ich de sc r ib e s t h i s ope r a t i o n i n de t a i l f o r t h eSPACE_FooDataReader class.

3.5.10.19 SPACE_FooDataReaderView_set_qos (inherited)This operation is inherited and therefore not described here. See the classDDS_DataReaderView for further explanation.

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReaderView_set_qos (SPACE_FooDataReaderView _this, const DDS_DataReaderViewQos *qos);

3.5.10.20 SPACE_FooDataReaderView_take

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReaderView_take (SPACE_FooDataReaderView _this, DDS_sequence_Foo *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

DescriptionT h i s o p e r a t i o n r e a ds a s e q u e n c e o f F o o s a m p l e s f r o m t h eSPACE_FooDataReaderView and by doing so, removes the data from theSPACE_FooDataReaderView, but not from the SPACE_FooDataReader that itbe longs to . For a fu l l desc r ip t ion p lease refer to Sect ion 3 .5 .2 .75 ,SPACE_FooDataReader_take, on page 495, which describes this operation in detailfor the SPACE_FooDataReader class.

562API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

3.5.10.21 SPACE_FooDataReaderView_take_instance

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReaderView_take_instance (SPACE_FooDataReaderView _this, DDS_sequence_Foo *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_SampleStateMask sample_states, const DDS_ViewStateMask view_states, const DDS_InstanceStateMask instance_states);

DescriptionThis operation reads a sequence of Foo samples of a single instance from theSPACE_FooDataReaderView and by doing so, removes the data from theSPACE_FooDataReaderView, but not from the SPACE_FooDataReader that itbe longs to . For a fu l l desc r ip t ion p lease refer to Sect ion 3 .5 .2 .76 ,SPACE_FooDataReader_take_instance, on page 497, which describes thisoperation in detail for the SPACE_FooDataReader class.

3.5.10.22 SPACE_FooDataReaderView_take_next_instance

Synopsis#include <Space.h>ReturnCode_t take_next_instance (FooSeq *data_values, SampleInfoSeq *info_seq, DDS_long max_samples, InstanceHandle_t a_handle, SampleStateMask sample_states, ViewStateMask view_states, InstanceStateMask instance_states);

DescriptionThis operation reads a sequence of Foo samples of the next single instance from theSPACE_FooDataReaderView and by doing so, removes the data from theSPACE_FooDataReaderView, but not from the SPACE_FooDataReader that itbe longs to . For a fu l l desc r ip t ion p lease refer to Sect ion 3 .5 .2 .77 ,SPACE_FooDataReader_take_next_instance, on page 499, which describes thisoperation in detail for the SPACE_FooDataReader class.

563API Reference

3 DCPS Classes and Operations 3.5 Subscription Module

3.5.10.23 SPACE_FooDataReaderView_take_next_instance_w_condition

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReaderView_take_next_instance_w_condition (SPACE_FooDataReaderView _this, DDS_sequence_Foo *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_InstanceHandle_t a_handle, const DDS_ReadCondition a_condition);

DescriptionThis operation reads a sequence of Foo samples of the next single instance from theSPACE_FooDataReaderView, f i l tered by a DDS_ReadCondition orDDS_QueryCondition and by doing so, removes the data f rom theSPACE_FooDataReaderView, but not from the SPACE_FooDataReader that itbe longs to . For a fu l l desc r ip t ion p lease refer to Sect ion 3 .5 .2 .78 ,SPACE_FooDataReader_take_next_instance_w_condition, on page 501, whichdescribes this operation in detail for the SPACE_FooDataReader class.

3.5.10.24 SPACE_FooDataReaderView_take_next_sample

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReaderView_take_next_sample (SPACE_FooDataReaderView _this, Foo *data_values, DDS_SampleInfo *sample_info);

NOTE: This operation is not yet implemented. It is scheduled for a future release.

3.5.10.25 SPACE_FooDataReaderView_take_w_condition

Synopsis#include <Space.h>DDS_ReturnCode_t SPACE_FooDataReaderView_take_w_condition (SPACE_FooDataReaderView _this, DDS_sequence_Foo *data_values, SampleInfoSeq *info_seq, const DDS_long max_samples, const DDS_ReadCondition a_condition);

564API Reference

3 DCPS Classes and Operations 3.6 QosProvider

DescriptionT h i s o p e r a t i o n r e a ds a s e q u e n c e o f F o o s a m p l e s f r o m t h eSPACE_FooDataReaderView, f i l tered by a DDS_ReadCondition orDDS_QueryCondition and by doing so, removes the data f rom theSPACE_FooDataReaderView, but not from the SPACE_FooDataReader that itbe longs to . For a fu l l desc r ip t ion p lease refer to Sect ion 3 .5 .2 .80 ,SPACE_FooDataReader_take_w_condition, on page 503, which describes thisoperation in detail for the SPACE_FooDataReader class.

3.6 QosProviderThe QosProvider API allows users to specify the QoS settings of their DCPSentities outside of application code in XML. The QosProvider is delivered as part ofthe DCPS API of OpenSplice and has no factory. It is not associated with aDDS_DomainParticipant, so it can be be obtained by a normal allocation.

3.6.1 Class DDS_QosProviderThe DDS_QosProvider class provides access to the QoS settings that are specifiedin an XML file. The interface is as follows:

/* Allocator */DDS_QosProvider DDS_QosProvider__alloc ( const char *uri, const char *profile);

/* API operations */DDS_ReturnCode_t DDS_QosProvider_get_participant_qos( DDS_QosProvider _this, DDS_DomainParticipantQos *qos, const char *id);

DDS_ReturnCode_t DDS_QosProvider_get_topic_qos( DDS_QosProvider _this, DDS_TopicQos *qos, const char *id);

DDS_ReturnCode_t DDS_QosProvider_get_subscriber_qos( DDS_QosProvider _this, DDS_SubscriberQos *qos, const char *id);

DDS_ReturnCode_t DDS_QosProvider_get_datareader_qos(

565API Reference

3 DCPS Classes and Operations 3.6 QosProvider

DDS_QosProvider _this, DDS_DataReaderQos *qos, const char *id);

DDS_ReturnCode_t DDS_QosProvider_get_publisher_qos( DDS_QosProvider _this, DDS_PublisherQos *qos, const char *id);

DDS_ReturnCode_t DDS_QosProvider_get_datawriter_qos( DDS_QosProvider _this, DDS_DataWriterQos *qos, const char *id);

3.6.1.1 DDS_QosProvider__alloc

Synopsis#include <dds_dcps.h>DDS_QosProvider DDS_QosProvider__alloc ( const char *uri, const char *profile);

DescriptionConstructs a new DDS_QosProvider based on the provided uri and profile.

Parametersin char * uri - A Uniform Resource Identifier (URI) that points to the location

where the QoS profile needs to be loaded from. Currently only URI’s with a‘file’ scheme that point to an XML file are supported. If profiles and/or QoSsettings are not uniquely identifiable by name within the resource pointed to byuri, a random one of them will be stored.

in char * profile - The name of the QoS profile that serves as the default QoSprofile for the DDS_QosProvider_get_*_qos(...) operations.

Return ValueA DDS_QosProvider instance that is instantiated with all profiles and/or QoS’s

loaded from the location specified by the provided uri.Construction of the DDS_QosProvider will fail under the followingconditions:— No uri is provided.— The resource pointed to by uri cannot be found.

566API Reference

3 DCPS Classes and Operations 3.6 QosProvider

— The content of the resource pointed to by uri is malformed (e.g., malformedXML).

3.6.1.2 DDS_QosProvider_get_participant_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_QosProvider_get_participant_qos( DDS_QosProvider _this, DDS_DomainParticipantQos *qos, const char *id);

DescriptionResolves the DDS_DomainParticipantQos identified by the id from the uri theDDS_QosProvider _this is associated with.

Parametersin DDS_QosProvider _this - The DDS_QosProvider on which the operation is

performed.inout DDS_DomainParticipantQos * qos - A pointer to the destination

DDS_DomainParticipantQos in which the QoS policy settings will becopied.

in char * id - The fully-qualified name that identifies a QoS within the uriassociated with the DDS_QosProvider or a name that identifies a QoS withinthe uri associated with the DDS_QosProvider instance relative to its defaultQoS profile. Id’s starting with ‘::’ are interpreted as fully-qualified names andall others are interpreted as names relative to the default QoS profile of theDDS_QosProvider instance. When id is NULL it is interpreted as a non-namedQoS within the default QoS profile associated with the DDS_QosProvider.

Return ValueThe operation may return:• DDS_RETCODE_OK - If qos has been initialized successfully.• DDS_RETCODE_NO_DATA - If no DDS_DomainParticipantQos that matches

the provided id can be found within the uri associated with theDDS_QosProvider.

• DDS_RETCODE_BAD_PARAMETER - If _this and/or qos is NULL.• DDS_RETCODE_PRECONDITION_NOT_MET - If the DDS_QosProvider instance

is not properly initialized.

567API Reference

3 DCPS Classes and Operations 3.6 QosProvider

• DDS_RETCODE_OUT_OF_RESOURCES - If not enough memory is available toperform the operation.

• DDS_RETCODE_ERROR - If an internal error occurred.

3.6.1.3 DDS_QosProvider_get_topic_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_QosProvider_get_topic_qos( DDS_QosProvider _this, DDS_TopicQos *qos, const char *id);

DescriptionResolves the DDS_TopicQos ident i f ied by the id f rom the uri theDDS_QosProvider _this is associated with.

Parametersin DDS_QosProvider _this - The DDS_QosProvider on which the operation

is performed.inout DDS_TopicQos * qos - A pointer to the destination DDS_TopicQos in

which the QoS policy settings will be copied.in char * id - The fully-qualified name that identifies a QoS within the uri

associated with the DDS_QosProvider or a name that identifies a QoS withinthe uri associated with the DDS_QosProvider instance relative to its defaultQoS profile. Id’s starting with ‘::’ are interpreted as fully-qualified names andall others are interpreted as names relative to the default QoS profile of theDDS_QosProvider instance. When id is NULL it is interpreted as a non-namedQoS within the default QoS profile associated with the DDS_QosProvider.

Return ValueThe operation may return:• DDS_RETCODE_OK - If qos has been initialized successfully.• DDS_RETCODE_NO_DATA - If no DDS_TopicQos that matches the provided id

can be found within the uri associated with the DDS_QosProvider.• DDS_RETCODE_BAD_PARAMETER - If _this and/or qos is NULL.• DDS_RETCODE_PRECONDITION_NOT_MET - If the DDS_QosProvider instance

is not properly initialized.

568API Reference

3 DCPS Classes and Operations 3.6 QosProvider

• DDS_RETCODE_OUT_OF_RESOURCES - If not enough memory is available toperform the operation.

• DDS_RETCODE_ERROR - If an internal error occurred.

3.6.1.4 DDS_QosProvider_get_subscriber_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_QosProvider_get_subscriber_qos( DDS_QosProvider _this, DDS_SubscriberQos *qos, const char *id);

DescriptionResolves the DDS_SubscriberQos identified by the id from the uri theDDS_QosProvider _this is associated with.

Parametersin DDS_QosProvider _this - The DDS_QosProvider on which the operation

is performed.inout DDS_SubscriberQos * qos - A pointer to the dest inat ion

DDS_SubscriberQos in which the QoS policy settings will be copied.in char * id - The fully-qualified name that identifies a QoS within the uri

associated with the DDS_QosProvider or a name that identifies a QoS withinthe uri associated with the DDS_QosProvider instance relative to its defaultQoS profile. Id’s starting with ‘::’ are interpreted as fully-qualified names andall others are interpreted as names relative to the default QoS profile of theDDS_QosProvider instance. When id is NULL it is interpreted as a non-namedQoS within the default QoS profile associated with the DDS_QosProvider.

Return ValueThe operation may return:• DDS_RETCODE_OK - If qos has been initialized successfully.• DDS_RETCODE_NO_DATA - If no DDS_SubscriberQos that matches the

provided id can be found within the uri associated with the DDS_QosProvider.• DDS_RETCODE_BAD_PARAMETER - If _this and/or qos is NULL.• DDS_RETCODE_PRECONDITION_NOT_MET - If the DDS_QosProvider instance

is not properly initialized.

569API Reference

3 DCPS Classes and Operations 3.6 QosProvider

• DDS_RETCODE_OUT_OF_RESOURCES - If not enough memory is available toperform the operation.

• DDS_RETCODE_ERROR - If an internal error occurred.

3.6.1.5 DDS_QosProvider_get_datareader_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_QosProvider_get_datareader_qos( DDS_QosProvider _this, DDS_DataReaderQos *qos, const char *id);

DescriptionResolves the DDS_DataReaderQos identified by the id from the uri theDDS_QosProvider _this is associated with.

Parametersin DDS_QosProvider _this - The DDS_QosProvider on which the operation

is performed.inout DDS_DataReaderQos * qos - A pointer to the dest inat ion

DDS_DataReaderQos in which the QoS policy settings will be copied.in char * id - The fully-qualified name that identifies a QoS within the uri

associated with the DDS_QosProvider or a name that identifies a QoS withinthe uri associated with the DDS_QosProvider instance relative to its defaultQoS profile. Id’s starting with ‘::’ are interpreted as fully-qualified names andall others are interpreted as names relative to the default QoS profile of theDDS_QosProvider instance. When id is NULL it is interpreted as a non-namedQoS within the default QoS profile associated with the DDS_QosProvider.

Return ValueThe operation may return:• DDS_RETCODE_OK - If qos has been initialized successfully.• DDS_RETCODE_NO_DATA - If no DDS_DataReaderQos that matches the

provided id can be found within the uri associated with the DDS_QosProvider.• DDS_RETCODE_BAD_PARAMETER - If _this and/or qos is NULL.• DDS_RETCODE_PRECONDITION_NOT_MET - If the DDS_QosProvider instance

is not properly initialized.

570API Reference

3 DCPS Classes and Operations 3.6 QosProvider

• DDS_RETCODE_OUT_OF_RESOURCES - If not enough memory is available toperform the operation.

• DDS_RETCODE_ERROR - If an internal error occurred.

3.6.1.6 DDS_QosProvider_get_publisher_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_QosProvider_get_publisher_qos( DDS_QosProvider _this, DDS_PublisherQos *qos, const char *id);

DescriptionResolves the DDS_PublisherQos identified by the id from the uri theDDS_QosProvider _this is associated with.

Parametersin DDS_QosProvider _this - The DDS_QosProvider on which the operation

is performed.inout DDS_PublisherQos * qos - A poin ter to the des t ina t ion

DDS_PublisherQos in which the QoS policy settings will be copied.in char * id - The fully-qualified name that identifies a QoS within the uri

associated with the DDS_QosProvider or a name that identifies a QoS withinthe uri associated with the DDS_QosProvider instance relative to its defaultQoS profile. Id’s starting with ‘::’ are interpreted as fully-qualified names andall others are interpreted as names relative to the default QoS profile of theDDS_QosProvider instance. When id is NULL it is interpreted as a non-namedQoS within the default QoS profile associated with the DDS_QosProvider.

Return ValueThe operation may return:• DDS_RETCODE_OK - If qos has been initialized successfully.• DDS_RETCODE_NO_DATA - If no DDS_PublisherQos that matches the providedid can be found within the uri associated with the DDS_QosProvider.

• DDS_RETCODE_BAD_PARAMETER - If _this and/or qos is NULL.• DDS_RETCODE_PRECONDITION_NOT_MET - If the DDS_QosProvider instance

is not properly initialized.

571API Reference

3 DCPS Classes and Operations 3.6 QosProvider

• DDS_RETCODE_OUT_OF_RESOURCES - If not enough memory is available toperform the operation.

• DDS_RETCODE_ERROR - If an internal error occurred.

3.6.1.7 DDS_QosProvider_get_datawriter_qos

Synopsis#include <dds_dcps.h>DDS_ReturnCode_t DDS_QosProvider_get_datawriter_qos( DDS_QosProvider _this, DDS_DataWriterQos *qos, const char *id);

DescriptionResolves the DDS_DataWriterQos identified by the id from the uri theDDS_QosProvider _this is associated with.

Parametersin DDS_QosProvider _this - The DDS_QosProvider on which the operation

is performed.inout DDS_DataWriterQos * qos - A pointer to the dest inat ion

DDS_DataWriterQos in which the QoS policy settings will be copied.in char * id - The fully-qualified name that identifies a QoS within the uri

associated with the DDS_QosProvider or a name that identifies a QoS withinthe uri associated with the DDS_QosProvider instance relative to its defaultQoS profile. Id’s starting with ‘::’ are interpreted as fully-qualified names andall others are interpreted as names relative to the default QoS profile of theDDS_QosProvider instance. When id is NULL it is interpreted as a non-namedQoS within the default QoS profile associated with the DDS_QosProvider.

Return ValueThe operation may return:• DDS_RETCODE_OK - If qos has been initialized successfully.• DDS_RETCODE_NO_DATA - If no DDS_DataWriterQos that matches the

provided id can be found within the uri associated with the DDS_QosProvider.• DDS_RETCODE_BAD_PARAMETER - If _this and/or qos is NULL.• DDS_RETCODE_PRECONDITION_NOT_MET - If the DDS_QosProvider instance

is not properly initialized.

572API Reference

3 DCPS Classes and Operations 3.6 QosProvider

• DDS_RETCODE_OUT_OF_RESOURCES - If not enough memory is available toperform the operation.

• DDS_RETCODE_ERROR - If an internal error occurred.

573API Reference

3 DCPS Classes and Operations 3.6 QosProvider

574API Reference

APPENDICES

Appendix

A Quality Of ServiceEach DDS_Entity is accompanied by an <DDS_Entity>Qos structure thatimplements the basic mechanism for an application to specify Quality of Serviceattributes. This structure consists of DDS_Entity specific QosPolicy attributes.QosPolicy attributes are structured types where each type specifies theinformation that controls an DDS_Entity related (configurable) attribute of theData Distribution Service.

Affected EntitiesEach DDS_Entity can be configured with a set of QosPolicy settings. However,any DDS_Entity canno t suppor t any QosPolicy. Fo r ins t ance , aDDS_DomainParticipant supports different QosPolicy settings than aDDS_Topic or a DDS_Publisher. The set of QosPolicy settings is implementedas a struct of QosPolicy structs, identified as <DDS_Entity>Qos. Each<DDS_Entity>Qos struct only contains those QosPolicy structs relevant to thespecific DDS_Entity. The <DDS_Entity>Qos struct serves as the parameter tooperations which require a Qos . <DDS_Entity>Qos struct is the APIimplementation of the QoS. Depending on the specific <DDS_Entity>Qos, itcontrols the behaviour of a DDS_Topic, DDS_DataWriter, DDS_DataReader,DDS_Publisher, DDS_Subscriber, DDS_DomainParticipant orDDS_DomainParticipantFactory1.

Basic UsageThe basic way to modify or set the <DDS_Entity>Qos is by using anDDS_<Entity>_get_qos operation to get all QosPolicy settings from thisDDS_Entity (that is the <DDS_Entity>Qos), modify several specific QosPolicysettings and put them back using an DDS_<DDS_Entity>_set_qos operation toset all QosPolicy settings on this DDS_Entity (that is the <DDS_Entity>Qos).An example o f these ope ra t ions fo r the DDS_DataWriterQos a re

1. Note that the DDS_DomainParticipantFactory is a special kind of entity: it does notinherit from DDS_Entity, nor does it have a DDS_Listener orDDS_StatusCondition, but its behaviour can be controlled by its own set ofQosPolicies.

577C Reference Guide

Appendices

DDS_Publisher_get_default_datawriter_qos and DDS_Publisher_set_default_datawriter_qos, which take the DDS_DataWriterQos as aparameter.The interface description of this struct is as follows:

/* * struct <name>QosPolicy * see appendix *//* * struct <DDS_Entity>Qos */

struct DDS_DomainParticipantFactoryQos { DDS_EntityFactoryQosPolicy entity_factory; };

struct DDS_DomainParticipantQos { DDS_UserDataQosPolicy user_data; DDS_EntityFactoryQosPolicy entity_factory; DDS_SchedulingQosPolicy watchdog_scheduling; DDS_SchedulingQosPolicy listener_scheduling; };struct DDS_TopicQos { DDS_TopicDataQosPolicy topic_data; DDS_DurabilityQosPolicy durability; DDS_DurabilityServiceQosPolicy durability_service; DDS_DeadlineQosPolicy deadline; DDS_LatencyBudgetQosPolicy latency_budget; DDS_LivelinessQosPolicy liveliness; DDS_ReliabilityQosPolicy reliability; DDS_DestinationOrderQosPolicy destination_order; DDS_HistoryQosPolicy history; DDS_ResourceLimitsQosPolicy resource_limits; DDS_TransportPriorityQosPolicy transport_priority; DDS_LifespanQosPolicy lifespan; DDS_OwnershipQosPolicy ownership; };struct DDS_DataWriterQos { DDS_DurabilityQosPolicy durability; DDS_DeadlineQosPolicy deadline; DDS_LatencyBudgetQosPolicy latency_budget; DDS_LivelinessQosPolicy liveliness; DDS_ReliabilityQosPolicy reliability; DDS_DestinationOrderQosPolicy destination_order; DDS_HistoryQosPolicy history; DDS_ResourceLimitsQosPolicy resource_limits; DDS_TransportPriorityQosPolicy transport_priority; DDS_LifespanQosPolicy lifespan; DDS_UserDataQosPolicy user_data; DDS_OwnershipQosPolicy ownership; DDS_OwnershipStrengthQosPolicy ownership_strength; DDS_WriterDataLifecycleQosPolicy writer_data_lifecycle;};struct DDS_PublisherQos

578C Reference Guide

Appendices

{ DDS_PresentationQosPolicy presentation; DDS_PartitionQosPolicy partition; DDS_GroupDataQosPolicy group_data; DDS_EntityFactoryQosPolicy entity_factory; };struct DDS_DataReaderQos { DDS_DurabilityQosPolicy durability; DDS_DeadlineQosPolicy deadline; DDS_LatencyBudgetQosPolicy latency_budget; DDS_LivelinessQosPolicy liveliness; DDS_ReliabilityQosPolicy reliability; DDS_DestinationOrderQosPolicy destination_order; DDS_HistoryQosPolicy history; DDS_ResourceLimitsQosPolicy resource_limits; DDS_UserDataQosPolicy user_data; DDS_OwnershipQosPolicy ownership; DDS_TimeBasedFilterQosPolicy time_based_filter; DDS_ReaderDataLifecycleQosPolicy reader_data_lifecycle;};struct DDS_SubscriberQos { DDS_PresentationQosPolicy presentation; DDS_PartitionQosPolicy partition; DDS_GroupDataQosPolicy group_data; DDS_EntityFactoryQosPolicy entity_factory; };

/* * define <DDS_Entity>_QOS_DEFAULT */

#define DDS_PARTICIPANT_QOS_DEFAULT#define DDS_TOPIC_QOS_DEFAULT#define DDS_DATAWRITER_QOS_DEFAULT#define DDS_PUBLISHER_QOS_DEFAULT#define DDS_DATAREADER_QOS_DEFAULT#define DDS_SUBSCRIBER_QOS_DEFAULT#define DDS_DATAWRITER_QOS_USE_TOPIC_QOS#define DDS_DATAREADER_QOS_USE_TOPIC_QOS

/* * implemented API operations * <no operations> */

The next paragraphs describe the usage of each <DDS_Entity>Qos struct.

DDS_DataReaderQosSynopsis#include <dds_dcps.h>

struct DDS_DataReaderQos { DDS_DurabilityQosPolicy durability; DDS_DeadlineQosPolicy deadline; DDS_LatencyBudgetQosPolicy latency_budget;

579C Reference Guide

Appendices

DDS_LivelinessQosPolicy liveliness; DDS_ReliabilityQosPolicy reliability; DDS_DestinationOrderQosPolicy destination_order; DDS_HistoryQosPolicy history; DDS_ResourceLimitsQosPolicy resource_limits; DDS_UserDataQosPolicy user_data; DDS_OwnershipQosPolicy ownership; DDS_TimeBasedFilterQosPolicy time_based_filter; DDS_ReaderDataLifecycleQosPolicy reader_data_lifecycle;};

DescriptionThis struct provides the basic mechanism for an application to specify Quality ofService attributes for a DDS_DataReader.

AttributesDDS_DurabilityQosPolicy durability - whether the data should be stored

for late joining readers. See Section 3.1.3.3 on page 73 for more detailedinformation about these settings.

DDS_DeadlineQosPolicy deadline - the period within which a new sample isexpected. See Section 3.1.3.1 on page 69 for more detailed information aboutthese settings.

DDS_LatencyBudgetQosPolicy latency_budget - used by the DataDistribution Service for optimization. See Section 3.1.3.8 on page 83 for moredetailed information about these settings.

DDS_LivelinessQosPolicy liveliness - the way the liveliness of theDDS_DataReader is asserted to the Data Distribution Service. See Section3.1.3.10 on page 85 for more detailed information about these settings.

DDS_ReliabilityQosPolicy reliability - the reliability of the datadistribution. See Section 3.1.3.16 on page 102 for more detailed informationabout these settings.

DDS_DestinationOrderQosPolicy destination_order - the order inwhich the DDS_DataReader timely orders the data. See Section 3.1.3.2 onpage 71 for more detailed information about these settings.

DDS_HistoryQosPolicy history - how samples should be stored. See Section3.1.3.7 on page 80 for more detailed information about these settings.

DDS_ResourceLimitsQosPolicy resource_limits - the maximum amountof resources to be used. See Section 3.1.3.17 on page 104 for more detailedinformation about these settings.

DDS_UserDataQosPolicy user_data - used to attach additional information tothe DDS_DataReader. See Section 3.1.3.22 on page 110 for more detailedinformation about these settings.

580C Reference Guide

Appendices

DDS_OwnershipQosPolicy ownership - whether a DataWriter exclusivelyowns an instance. See Section 3.1.3.11 on page 87 for more detailed informationabout these settings.

DDS_TimeBasedFilterQosPolicy time_based_filter - the maximum datarate at which the DDS_DataReader will receive changes. See Section 3.1.3.19on page 107 for more detailed information about these settings.

DDS_ReaderDataLifecycleQosPolicy reader_data_lifecycle -de t e rmines whe the r i n s t an c e s t a t e c h a n g e s ( e i t h e rDDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE o rDDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE) are presented to the userwhen no corresponding samples are available to communicate them. Also itdetermines how long an instance state change remains available to a user thatdoes not explicitly consume them. See Section 3.1.3.15 on page 99 for moredetailed information about these settings.

Detailed DescriptionA QosPolicy can be set when the DDS_DataReader is created with theDDS_Subscriber_create_datareader operation (or modified with theDDS_DataReader_set_qos ope ra t ion ) . Bo th ope ra t ions t ake theDDS_DataReaderQos struct as a parameter. There may be cases where severalpolicies are in conflict. Consistency checking is performed each time the policiesare modified when they are being created and, in case they are already enabled, viathe DDS_DataReader_set_qos operation.Some QosPolicy have “immutable” semantics meaning that they can only bespecified either at DDS_DataReader creation time or prior to calling theDDS_DataReader_enable operation on the DDS_DataReader.See Struct QosPolicy on page 59 for a list of all <name>QosPolicy settings, theirmeaning, characteristics and possible values, as well as if it applies to aDDS_DataReader.The initial value of the default DDS_DataReaderQos in the DDS_Subscriber aregiven in the following table:

Table 19: DDS_DATAREADER_QOS_DEFAULT

QosPolicy Attribute Valuedurability kind DDS_VOLATILE_DURABILITY_QOS

deadline period DDS_DURATION_INFINITE

latency_budget duration 0

581C Reference Guide

Appendices

DDS_DataWriterQosSynopsis#include <dds_dcps.h>struct DDS_DataWriterQos

{ DDS_DurabilityQosPolicy durability; DDS_DeadlineQosPolicy deadline; DDS_LatencyBudgetQosPolicy latency_budget; DDS_LivelinessQosPolicy liveliness; DDS_ReliabilityQosPolicy reliability; DDS_DestinationOrderQosPolicy destination_order; DDS_HistoryQosPolicy history; DDS_ResourceLimitsQosPolicy resource_limits; DDS_TransportPriorityQosPolicy transport_priority;

liveliness kind DDS_AUTOMATIC_LIVELINESS_QOS

lease_duration DDS_DURATION_INFINITE

reliability kind DDS_BEST_EFFORT_RELIABILITY_QOS

max_blocking_time 100 ms

synchronous FALSE

destination_order kind DDS_BY_RECEPTION_ TIMESTAMP_DESTINATIONORDER_QOS

history kind DDS_KEEP_LAST_HISTORY_QOS

depth 1

resource_limits max_samples DDS_LENGTH_UNLIMITED

max_instances DDS_LENGTH_UNLIMITED

max_samples_ per_instance DDS_LENGTH_UNLIMITED

user_data value.length 0

ownership kind DDS_SHARED_OWNERSHIP_QOS

time_based_filter minimum_separation 0

reader_data_lifecycle autopurge_ nowriter_samples_delay

DDS_DURATION_INFINITE

autopurge_ disposed_samples_delay

DDS_DURATION_INFINITE

autopurge_dispose_all FALSE

enable_invalid_samples TRUE

invalid_sample_visibility.kind

DDS_MINIMUM_INVALID_SAMPLES

Table 19: DDS_DATAREADER_QOS_DEFAULT

QosPolicy Attribute Value

582C Reference Guide

Appendices

DDS_LifespanQosPolicy lifespan; DDS_UserDataQosPolicy user_data; DDS_OwnershipQosPolicy ownership; DDS_OwnershipStrengthQosPolicy ownership_strength; DDS_WriterDataLifecycleQosPolicy writer_data_lifecycle;};

DescriptionThis struct provides the basic mechanism for an application to specify Quality ofService attributes for a DDS_DataWriter.

AttributesDDS_DurabilityQosPolicy durability - whether the data should be stored

for late joining readers. See Section 3.1.3.3 on page 73 for more detailedinformation about these settings.

DDS_DeadlineQosPolicy deadline - the period within which a new sample iswritten. See Section 3.1.3.1 on page 69 for more detailed information aboutthese settings.

DDS_LatencyBudgetQosPolicy latency_budget - used by the DataDistribution Service for optimization. See Section 3.1.3.8 on page 83 for moredetailed information about these settings.

DDS_LivelinessQosPolicy liveliness - the way the liveliness of theDDS_DataWriter is asserted to the Data Distribution Service. See Section3.1.3.10 on page 85 for more detailed information about these settings.

DDS_ReliabilityQosPolicy reliability - the reliability of the datadistribution. See Section 3.1.3.16 on page 102 for more detailed informationabout these settings.

DDS_DestinationOrderQosPolicy destination_order - the order inwhich the DDS_DataReader timely orders the data. See Section 3.1.3.2 onpage 71 for more detailed information about these settings.

DDS_HistoryQosPolicy history - how samples should be stored. See Section3.1.3.7 on page 80 for more detailed information about these settings.

DDS_ResourceLimitsQosPolicy resource_limits - the maximum amountof resources to be used. See Section 3.1.3.17 on page 104 for more detailedinformation about these settings.

DDS_TransportPriorityQosPolicy transport_priority - a priority hintfor the underlying transport layer. See Section 3.1.3.21 on page 109 for moredetailed information about these settings.

DDS_LifespanQosPolicy lifespan - the maximum duration of validity of thedata written by the DDS_DataWriter. See Section 3.1.3.9 on page 84 for moredetailed information about these settings.

583C Reference Guide

Appendices

DDS_UserDataQosPolicy user_data - used to attach additional information tothe DDS_DataWriter. See Section 3.1.3.22 on page 110 for more detailedinformation about these settings.

DDS_OwnershipQosPolicy ownership - whether a DataWriter exclusivelyowns an instance. See Section 3.1.3.11 on page 87 for more detailed informationabout these settings.

DDS_OwnershipStrengthQosPolicy ownership_strength - the strength todetermine the ownership. See Section 3.1.3.12 on page 90 for more detailedinformation about these settings.

DDS_WriterDataLifecycleQosPolicy writer_data_lifecycle - whetherunregistered instances are disposed of automatically or not. See Section 3.1.3.23on page 110 for more detailed information about these settings.

Detailed DescriptionA QosPolicy can be set when the DDS_DataWriter is created with theDDS_Publisher_create_datawriter operation (or modified with theDDS_DataWriter_set_qos ope ra t ion ) . Bo th ope ra t ions t ake theDDS_DataWriterQos struct as a parameter. There may be cases where severalpolicies are in conflict. Consistency checking is performed each time the policiesare modified when they are being created and, in case they are already enabled, viathe DDS_DataWriter_set_qos operation.Some QosPolicy have “immutable” semantics meaning that they can only bespecified either at DDS_DataWriter creation time or prior to calling theDDS_DataWriter_enable operation on the DDS_DataWriter.The Struct QosPolicy provides the list of all <name>QosPolicy settings, theirmeaning, characteristics and possible values, as well as if it applies to aDDS_DataWriter.The initial value of the default DDS_DataWriterQos in the DDS_Publisher aregiven in the following table:

Table 20: DDS_DATAWRITER_QOS_DEFAULT

QosPolicy Attribute Valuedurability kind DDS_VOLATILE_DURABILITY_QOS

deadline period DDS_DURATION_INFINITE

latency_budget duration 0

liveliness kind DDS_AUTOMATIC_LIVELINESS_QOS

lease_duration DDS_DURATION_INFINITE

584C Reference Guide

Appendices

DDS_DomainParticipantFactoryQosSynopsis#include <dds_dcps.h>struct DDS_DomainParticipantFactoryQos

{ DDS_EntityFactoryQosPolicy entity_factory; };

DescriptionThis struct provides the basic mechanism for an application to specify Quality ofService attributes for a DDS_DomainParticipantFactory.

AttributesDDS_EntityFactoryQosPolicy entity_factory - whether a just created

DomainParticipant should be enabled. See Section 3.1.3.5 on page 79 formore detailed information about these settings.

reliability kind DDS_BEST_EFFORT_RELIABILITY_QOS

max_blocking_time 100 ms

synchronous FALSE

destination_order kind DDS_BY_RECEPTION_ TIMESTAMP_DESTINATIONORDER_QOS

history kind DDS_KEEP_LAST_HISTORY_QOS

depth 1

resource_limits max_samples DDS_LENGTH_UNLIMITED

max_instances DDS_LENGTH_UNLIMITED

max_samples_ per_instance

DDS_LENGTH_UNLIMITED

transport_priority value 0

lifespan duration DDS_DURATION_INFINITE

user_data value.length 0

ownership kind DDS_SHARED_OWNERSHIP_QOS

ownership_strength value 0

writer_data_lifecycle autodispose_ unregistered_instances

TRUE

Table 20: DDS_DATAWRITER_QOS_DEFAULT (Continued)

QosPolicy Attribute Value

585C Reference Guide

Appendices

Detailed DescriptionThe QosPolicy c a n n o t b e s e t a t c r e a t i o n t i m e , s i n c e t h eDDS_DomainParticipantFactory is a pre-existing object that can only beobtained with the DDS_DomainParticipantFactory_get_instance operationor its alias DDS_TheParticipantFactory. Therefore its QosPolicy isinitialized to a default value according to Table 21::

A f t e r c r e a t i o n t h e QosPolicy c a n b e m od i f i e d w i th t h eDDS_DomainParticipantFactory_set_qos operation, which takes theDDS_DomainParticipantFactoryQos struct as a parameter.

DDS_DomainParticipantQosSynopsis#include <dds_dcps.h>struct DDS_DomainParticipantQos

{ DDS_UserDataQosPolicy user_data; DDS_EntityFactoryQosPolicy entity_factory; DDS_SchedulingQosPolicy watchdog_scheduling; DDS_SchedulingQosPolicy listener_scheduling; };

DescriptionThis struct provides the basic mechanism for an application to specify Quality ofService attributes for a DDS_DomainParticipant.

AttributesDDS_UserDataQosPolicy user_data - used to attach additional information to

the DDS_DomainParticipant. See Section 3.1.3.22 on page 110 for moredetailed information about these settings.

DDS_EntityFactoryQosPolicy entity_factory - whether a just createdDDS_Entity should be enabled. See Section 3.1.3.5 on page 79 for moredetailed information about these settings.

DDS_SchedulingQosPolicy watchdog_scheduling - the schedulingparameters used to create the watchdog thread. See Section 3.1.3.18 on page106 for more detailed information about these settings.

Table 21: Default Values for DDS_DomainParticipantFactoryQos

QosPolicy Attribute Valueentity_factory autoenable_created_entities TRUE

586C Reference Guide

Appendices

DDS_SchedulingQosPolicy listener_scheduling - the schedulingparameters used to create the listener thread. See Section 3.1.3.18 on page 106for more detailed information about these settings.

Detailed DescriptionA DDS_DomainParticipant will spawn different threads for different purposes:• A listener thread is spawned to perform the callbacks to all DDS_Listener

objects attached to the various DDS_Entities contained in theDDS_DomainParticipant. The scheduling parameters for this thread can bespecified in the listener_scheduling field of theDDS_DomainParticipantQos.

• A watchdog thread is spawned to report the the Liveliness of all DDS_Entitiescontained in the DDS_DomainParticipant whoseDDS_LivelinessQosPolicyKind in their DDS_LivelinessQosPolicy isset to DDS_AUTOMATIC_LIVELINESS_QOS. The scheduling parameters for thisthread can be specified in the watchdog_scheduling field of theDDS_DomainParticipantQos.

A QosPolicy can be set when the DDS_DomainParticipant is created with theDDS_DomainParticipantFactory_create_participant operation (ormodified with the DDS_DomainParticipant_set_qos operation). Bothoperations take the DDS_DomainParticipantQos struct as a parameter. Theremay be cases where several policies are in conflict. Consistency checking isperformed each time the policies are modified when they are being created and, incase they are already enabled, via the DDS_DomainParticipant_set_qosoperation.Some QosPolicy have “immutable” semantics meaning that they can only bespecified either at DDS_DomainParticipant creation time or prior to calling theDDS_DomainParticipant_enable o p e r a t i o n o n t h eDDS_DomainParticipant.The initial value of the default DDS_DomainParticipantQos in theDDS_DomainParticipantFactory are given in the following table:

Table 22: DDS_PARTICIPANT_QOS_DEFAULT

QosPolicy Attribute Valueuser_data value.length 0

entity_factory autoenable_created_entities TRUE

watchdog_scheduling scheduling_class.kind SCHEDULE_DEFAULT

scheduling_priority_kind.kind PRIORITY_RELATIVE

scheduling_priority 0

587C Reference Guide

Appendices

DDS_PublisherQosSynopsis#include <dds_dcps.h>struct DDS_PublisherQos

{ DDS_PresentationQosPolicy presentation; DDS_PartitionQosPolicy partition; DDS_GroupDataQosPolicy group_data; DDS_EntityFactoryQosPolicy entity_factory; };

DescriptionThis struct provides the basic mechanism for an application to specify Quality ofService attributes for a DDS_Publisher.

AttributesDDS_PresentationQosPolicy presentation - the dependency of changes to

data-instances. See Section 3.1.3.14 on page 92 for more detailed informationabout these settings.

DDS_PartitionQosPolicy partition - the partitions in which theDDS_Publisher is active. See Section 3.1.3.13 on page 91 for more detailedinformation about these settings.

DDS_GroupDataQosPolicy group_data - used to attach additional informationto the DDS_Publisher. See Section 3.1.3.6 on page 80 for more detailedinformation about these settings.

DDS_EntityFactoryQosPolicy entity_factory - whether a just createdDDS_DataWriter should be enabled. See Section 3.1.3.5 on page 79 for moredetailed information about these settings.

Detailed DescriptionA QosPolicy can be set when the DDS_Publisher is created with theDDS_DomainParticipant_create_publisher operation (or modified with theDDS_Publisher_set_qos o p e r a t i o n ) . B o t h o p e ra t i o n s t a k e t h eDDS_PublisherQos struct as a parameter. There may be cases where several

listener_scheduling scheduling_class.kind SCHEDULE_DEFAULT

scheduling_priority_kind.kind PRIORITY_RELATIVE

scheduling_priority 0

Table 22: DDS_PARTICIPANT_QOS_DEFAULT

QosPolicy Attribute Value

588C Reference Guide

Appendices

policies are in conflict. Consistency checking is performed each time the policiesare modified when they are being created and, in case they are already enabled, viathe DDS_Publisher_set_qos operation.Some QosPolicy have “immutable” semantics meaning that they can only bespecified either at DDS_Publisher creation time or prior to calling theDDS_Publisher_enable operation on the DDS_Publisher.T h e in i t i a l v a l u e o f t h e d e f a u l t DDS_PublisherQos i n t h eDDS_DomainParticipant are given in the following table:

DDS_SubscriberQosSynopsis#include <dds_dcps.h>struct DDS_SubscriberQos

{ DDS_PresentationQosPolicy presentation; DDS_PartitionQosPolicy partition; DDS_GroupDataQosPolicy group_data; DDS_EntityFactoryQosPolicy entity_factory; };

DescriptionThis struct provides the basic mechanism for an application to specify Quality ofService attributes for a DDS_Subscriber.

AttributesDDS_PresentationQosPolicy presentation - the dependency of changes to

data-instances. See Section 3.1.3.14 on page 92 for more detailed informationabout these settings.

DDS_PartitionQosPolicy partition - the partitions in which theDDS_Subscriber is active. See Section 3.1.3.13 on page 91 for more detailedinformation about these settings.

Table 23: DDS_PUBLISHER_QOS_DEFAULT

QosPolicy Attribute Valuepresentation access_scope DDS_INSTANCE_PRESENTATION_QOS

coherent_access FALSE

ordered_access FALSE

partition name.length 0

group_data value.length 0

entity_factory autoenable_ created_entities

TRUE

589C Reference Guide

Appendices

DDS_GroupDataQosPolicy group_data - used to attach additional informationto the DDS_Subscriber. See Section 3.1.3.6 on page 80 for more detailedinformation about these settings.

DDS_EntityFactoryQosPolicy entity_factory - whether a just createdDDS_DataReader should be enabled. See Section 3.1.3.5 on page 79 for moredetailed information about these settings.

Detailed DescriptionA QosPolicy can be set when the DDS_Subscriber is created with theDDS_DomainParticipant_create_subscriber operation (or modified withthe DDS_Subscriber_set_qos operation). Both operations take theDDS_SubscriberQos struct as a parameter. There may be cases where severalpolicies are in conflict. Consistency checking is performed each time the policiesare modified when they are being created and, in case they are already enabled, viathe DDS_Subscriber_set_qos operation.Some QosPolicy have “immutable” semantics meaning that they can only bespecified either at DDS_Subscriber creation time or prior to calling theDDS_Subscriber_enable operation on the DDS_Subscriber.T h e i n i t i a l v a lu e o f t h e d e f a u l t DDS_SubscriberQos i n t h eDDS_DomainParticipant are given in the following table:

DDS_TopicQosSynopsis#include <dds_dcps.h>struct DDS_TopicQos

{ DDS_TopicDataQosPolicy topic_data; DDS_DurabilityQosPolicy durability; DDS_DurabilityServiceQosPolicy durability_service;

Table 24: DDS_SUBSCRIBER_QOS_DEFAULT

QosPolicy Attribute Valuepresentation access_scope DDS_INSTANCE_PRESENTATION_QOS

coherent_access FALSE

ordered_access FALSE

partition name.length 0

group_data value.length 0

entity_factory autoenable_ created_entities

TRUE

590C Reference Guide

Appendices

DDS_DeadlineQosPolicy deadline; DDS_LatencyBudgetQosPolicy latency_budget; DDS_LivelinessQosPolicy liveliness; DDS_ReliabilityQosPolicy reliability; DDS_DestinationOrderQosPolicy destination_order; DDS_HistoryQosPolicy history; DDS_ResourceLimitsQosPolicy resource_limits; DDS_TransportPriorityQosPolicy transport_priority; DDS_LifespanQosPolicy lifespan; DDS_OwnershipQosPolicy ownership; };

DescriptionThis struct provides the basic mechanism for an application to specify Quality ofService attributes for a DDS_Topic.

AttributesDDS_TopicDataQosPolicy topic_data - used to attach additional information

to the DDS_Topic. See Section 3.1.3.20 on page 108 for more detailedinformation about these settings.

DDS_DurabilityQosPolicy durability - whether the data should be storedfor late joining readers. See Section 3.1.3.3 on page 73 for more detailedinformation about these settings.

DDS_DurabilityServiceQosPolicy durability_service - the behaviourof the “transient/persistent service” of the Data Distribution System regardingTransient and Persistent DDS_Topic instances. See Section 3.1.3.4 on page 76for more detailed information about these settings.

DDS_DeadlineQosPolicy deadline - the period within which a new sample isexpected or written. See Section 3.1.3.1 on page 69 for more detailedinformation about these settings.

DDS_LatencyBudgetQosPolicy latency_budget - used by the DataDistribution Service for optimization. See Section 3.1.3.8 on page 83 for moredetailed information about these settings.

DDS_LivelinessQosPolicy liveliness - the way the liveliness of theDDS_Topic is asserted to the Data Distribution Service. See Section 3.1.3.10 onpage 85 for more detailed information about these settings.

DDS_ReliabilityQosPolicy reliability - the reliability of the datadistribution. See Section 3.1.3.16 on page 102 for more detailed informationabout these settings.

DDS_DestinationOrderQosPolicy destination_order - the order inwhich the DDS_DataReader timely orders the data. See Section 3.1.3.2 onpage 71 for more detailed information about these settings.

591C Reference Guide

Appendices

DDS_HistoryQosPolicy history - how samples should be stored. See Section3.1.3.7 on page 80 for more detailed information about these settings.

DDS_ResourceLimitsQosPolicy resource_limits - the maximum amountof resources to be used. See Section 3.1.3.17 on page 104 for more detailedinformation about these settings.

DDS_TransportPriorityQosPolicy transport_priority - a priority hintfor the underlying transport layer. See Section 3.1.3.21 on page 109 for moredetailed information about these settings.

DDS_LifespanQosPolicy lifespan - the maximum duration of validity of thedata written by a DDS_DataWriter. See Section 3.1.3.9 on page 84 for moredetailed information about these settings.

DDS_OwnershipQosPolicy ownership - whether a DDS_DataWriterexclusively owns an instance. See Section 3.1.3.11 on page 87 for more detailedinformation about these settings.

Detailed DescriptionA QosPolicy can be se t when the DDS_Topic i s c rea ted wi th theDDS_DomainParticipant_create_topic operation (or modified with theDDS_Topic_set_qos operation). Both operations take the DDS_TopicQos structas a parameter. There may be cases where several policies are in conflict.Consistency checking is performed each time the policies are modified when theya r e b e i n g c r e a t e d a n d , i n c a s e t he y a r e a l r e a d y e na b l e d , v i a t h eDDS_Topic_set_qos operation.Some QosPolicy have “immutable” semantics meaning that they can only bespecif ied e i ther a t DDS_Topic c rea t ion t ime or pr ior to ca l l ing theDDS_Topic_enable operation on the DDS_Topic.The initial value of the default DDS_TopicQos in the DDS_DomainParticipantare given in the following table:

Table 25: DDS_TOPIC_QOS_DEFAULT

QosPolicy Attribute Valuetopic_data value.length 0

durability kind DDS_VOLATILE_DURABILITY_QOS

592C Reference Guide

Appendices

durability_service service_cleanup_delay 0

history_kind DDS_KEEP_LAST_HISTORY_QOS

history_depth 1

max_samples DDS_LENGTH_UNLIMITED

max_instances DDS_LENGTH_UNLIMITED

max_samples_per_instance DDS_LENGTH_UNLIMITED

deadline period DDS_DURATION_INFINITE

latency_budget duration 0

liveliness kind DDS_AUTOMATIC_LIVELINESS_QOS

lease_duration DDS_DURATION_INFINITE

reliability kind DDS_BEST_EFFORT_RELIABILITY_QOS

max_blocking_time 100 ms

synchronous FALSE

destination_order kind DDS_BY_RECEPTION_ TIMESTAMP_DESTINATIONORDER_QOS

history kind DDS_KEEP_LAST_HISTORY_QOS

depth 1

resource_limits max_samples DDS_LENGTH_UNLIMITED

max_instances DDS_LENGTH_UNLIMITED

max_samples_per_instance DDS_LENGTH_UNLIMITED

transport_priority value 0

lifespan duration DDS_DURATION_INFINITE

ownership kind DDS_SHARED_OWNERSHIP_QOS

Table 25: DDS_TOPIC_QOS_DEFAULT (Continued)

QosPolicy Attribute Value

593C Reference Guide

Appendices

594C Reference Guide

Appendix

B API Constants and TypesThese constants and types are taken from the dds_dcps.h include file./* Duration and Time*/ struct DDS_Duration_t { DDS_long sec; DDS_unsigned_long nanosec; }; #define DDS_DURATION_INFINITE_SEC 0x7fffffff #define DDS_DURATION_INFINITE_NSEC 0x7fffffffU #define DDS_DURATION_ZERO_SEC 0 #define DDS_DURATION_ZERO_NSEC 0U #define DDS_DURATION_INFINITE {

DDS_DURATION_INFINITE_SEC,DDS_DURATION_INFINITE_NSEC }

#define DDS_DURATION_ZERO { DDS_DURATION_ZERO_SEC,DDS_DURATION_ZERO_NSEC }

struct DDS_Time_t { DDS_long sec; DDS_unsigned_long nanosec; };

/* * Pre-defined values * */ #define DDS_HANDLE_NIL DDS_HANDLE_NIL_NATIVE #define DDS_LENGTH_UNLIMITED -1 #define DDS_TIMESTAMP_INVALID_SEC -1 #define DDS_TIMESTAMP_INVALID_NSEC 4294967295U #define DDS_TIMESTAMP_INVALID {

DDS_TIMESTAMP_INVALID_SEC,DDS_TIMESTAMP_INVALID_NSEC }

/* ----- * Return codes * ----- */ #define DDS_RETCODE_OK 0

595C Reference Guide

Appendices

#define DDS_RETCODE_ERROR 1 #define DDS_RETCODE_UNSUPPORTED 2 #define DDS_RETCODE_BAD_PARAMETER 3 #define DDS_RETCODE_PRECONDITION_NOT_MET 4 #define DDS_RETCODE_OUT_OF_RESOURCES 5 #define DDS_RETCODE_NOT_ENABLED 6 #define DDS_RETCODE_IMMUTABLE_POLICY 7 #define DDS_RETCODE_INCONSISTENT_POLICY 8 #define DDS_RETCODE_ALREADY_DELETED 9 #define DDS_RETCODE_TIMEOUT 10 #define DDS_RETCODE_NO_DATA 11 #define DDS_RETCODE_ILLEGAL_OPERATION 12

/* ----- * DDS_Status to support listeners and conditions * ----- */ #define DDS_INCONSISTENT_TOPIC_STATUS 1U #define DDS_OFFERED_DEADLINE_MISSED_STATUS 2U #define DDS_REQUESTED_DEADLINE_MISSED_STATUS 4U #define DDS_OFFERED_INCOMPATIBLE_QOS_STATUS 32U #define DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS 64U #define DDS_SAMPLE_LOST_STATUS 128U #define DDS_SAMPLE_REJECTED_STATUS 256U #define DDS_DATA_ON_READERS_STATUS 512U #define DDS_DATA_AVAILABLE_STATUS 1024U #define DDS_LIVELINESS_LOST_STATUS 2048U #define DDS_LIVELINESS_CHANGED_STATUS 4096U #define DDS_PUBLICATION_MATCHED_STATUS 8192U #define DDS_SUBSCRIPTION_MATCHED_STATUS 16384U

#define DDS_ANY_STATUS 0x7FE7 #define DDS_STATUS_MASK_ANY_V1_2 0x7FE7 #define DDS_STATUS_MASK_NONE 0x0

/* * States * *//* * Sample states to support reads */ #define DDS_READ_SAMPLE_STATE 1U #define DDS_NOT_READ_SAMPLE_STATE 2U/* * This is a bit-mask DDS_SampleStateKind */ #define DDS_ANY_SAMPLE_STATE 65535U

/*

596C Reference Guide

Appendices

* View states to support reads */ #define DDS_NEW_VIEW_STATE 1U #define DDS_NOT_NEW_VIEW_STATE 2U/* * This is a bit-mask DDS_ViewStateKind */ #define DDS_ANY_VIEW_STATE 65535U /* * Instance states to support reads */ #define DDS_ALIVE_INSTANCE_STATE 1U #define DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE 2U #define DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE 4U /* * This is a bit-mask DDS_InstanceStateKind */ #define DDS_ANY_INSTANCE_STATE 65535U #define DDS_NOT_ALIVE_INSTANCE_STATE 6U /* * Participant Factory define */ #define TheParticipantFactory

(DDS_DomainParticipantFactory_get_instance())

/* * Qos defines * */#define DDS_PARTICIPANT_QOS_DEFAULT NULL#define DDS_TOPIC_QOS_DEFAULT NULL#define DDS_PUBLISHER_QOS_DEFAULT NULL#define DDS_SUBSCRIBER_QOS_DEFAULT NULL#define DDS_DATAREADER_QOS_DEFAULT NULL#define DDS_DATAWRITER_QOS_DEFAULT NULL#define DDS_DATAWRITER_QOS_USE_TOPIC_QOS ((DDS_DataWriterQos *)-1)#define DDS_DATAREADER_QOS_USE_TOPIC_QOS ((DDS_DataReaderQos *)-1)

/* QosPolicy * / #define DDS_USERDATA_QOS_POLICY_NAME "UserData" #define DDS_DURABILITY_QOS_POLICY_NAME "Durability" #define DDS_PRESENTATION_QOS_POLICY_NAME "Presentation" #define DDS_DEADLINE_QOS_POLICY_NAME "Deadline" #define DDS_LATENCYBUDGET_QOS_POLICY_NAME "LatencyBudget" #define DDS_OWNERSHIP_QOS_POLICY_NAME "Ownership" #define DDS_OWNERSHIPSTRENGTH_QOS_POLICY_NAME "OwnershipStrength"

597C Reference Guide

Appendices

#define DDS_LIVELINESS_QOS_POLICY_NAME "Liveliness" #define DDS_TIMEBASEDFILTER_QOS_POLICY_NAME "TimeBasedFilter" #define DDS_PARTITION_QOS_POLICY_NAME "Partition" #define DDS_RELIABILITY_QOS_POLICY_NAME "Reliability" #define DDS_DESTINATIONORDER_QOS_POLICY_NAME "DestinationOrder" #define DDS_HISTORY_QOS_POLICY_NAME "History" #define DDS_RESOURCELIMITS_QOS_POLICY_NAME "ResourceLimits" #define DDS_ENTITYFACTORY_QOS_POLICY_NAME "EntityFactory" #define DDS_WRITERDATALIFECYCLE_QOS_POLICY_NAME

"WriterDataLifecycle" #define DDS_READERDATALIFECYCLE_QOS_POLICY_NAME

"ReaderDataLifecycle" #define DDS_TOPICDATA_QOS_POLICY_NAME "TopicData" #define DDS_GROUPDATA_QOS_POLICY_NAME "GroupData" #define DDS_TRANSPORTPRIORITY_QOS_POLICY_NAME "TransportPriority" #define DDS_LIFESPAN_QOS_POLICY_NAME "Lifespan" #define DDS_DURABILITYSERVICE_QOS_POLICY_NAME "DurabilityService"

#define DDS_INVALID_QOS_POLICY_ID 0 #define DDS_USERDATA_QOS_POLICY_ID 1 #define DDS_DURABILITY_QOS_POLICY_ID 2 #define DDS_PRESENTATION_QOS_POLICY_ID 3 #define DDS_DEADLINE_QOS_POLICY_ID 4 #define DDS_LATENCYBUDGET_QOS_POLICY_ID 5 #define DDS_OWNERSHIP_QOS_POLICY_ID 6 #define DDS_OWNERSHIPSTRENGTH_QOS_POLICY_ID 7 #define DDS_LIVELINESS_QOS_POLICY_ID 8 #define DDS_TIMEBASEDFILTER_QOS_POLICY_ID 9 #define DDS_PARTITION_QOS_POLICY_ID 10 #define DDS_RELIABILITY_QOS_POLICY_ID 11 #define DDS_DESTINATIONORDER_QOS_POLICY_ID 12 #define DDS_HISTORY_QOS_POLICY_ID 13 #define DDS_RESOURCELIMITS_QOS_POLICY_ID 14 #define DDS_ENTITYFACTORY_QOS_POLICY_ID 15 #define DDS_WRITERDATALIFECYCLE_QOS_POLICY_ID 16 #define DDS_READERDATALIFECYCLE_QOS_POLICY_ID 17 #define DDS_TOPICDATA_QOS_POLICY_ID 18 #define DDS_GROUPDATA_QOS_POLICY_ID 19 #define DDS_TRANSPORTPRIORITY_QOS_POLICY_ID 20 #define DDS_LIFESPAN_QOS_POLICY_ID 21 #define DDS_DURABILITYSERVICE_QOS_POLICY_ID 22

598C Reference Guide

Appendix

C Platform Specific IDL InterfaceThe IDL code in the next paragraphs are taken from the OMG C Language MappingSpecification.

dds_dcps.idl#define DOMAINID_TYPE_NATIVE long#define HANDLE_TYPE_NATIVElong long#define HANDLE_NIL_NATIVE0#define BUILTIN_TOPIC_KEY_TYPE_NATIVElong#define TheParticipantFactory#define PARTICIPANT_QOS_DEFAULT#define TOPIC_QOS_DEFAULT#define PUBLISHER_QOS_DEFAULT#define SUBSCRIBER_QOS_DEFAULT#define DATAWRITER_QOS_DEFAULT#define DATAREADER_QOS_DEFAULT#define DATAWRITER_QOS_USE_TOPIC_QOS#define DATAREADER_QOS_USE_TOPIC_QOSmodule DDS { typedef DOMAINID_TYPE_NATIVE DomainId_t; typedef HANDLE_TYPE_NATIVE InstanceHandle_t; typedef BUILTIN_TOPIC_KEY_TYPE_NATIVE BuiltinTopicKey_t[3]; typedef sequence<InstanceHandle_t> InstanceHandleSeq; typedef long ReturnCode_t; typedef long QosPolicyId_t; typedef sequence<string> StringSeq; struct Duration_t {

long sec;unsigned long nanosec;

}; struct Time_t {

long sec;unsigned long nanosec;

}; // // Pre-defined values // const InstanceHandle_t HANDLE_NIL= HANDLE_NIL_NATIVE; const long LENGTH_UNLIMITED= -1; const long DURATION_INFINITE_SEC= 0x7fffffff; const unsigned long DURATION_INFINITE_NSEC= 0x7fffffff; const long DURATION_ZERO_SEC= 0;

599C Reference Guide

Appendices

const unsigned long DURATION_ZERO_NSEC= 0; const long TIMESTAMP_INVALID_SEC= -1; const unsigned long TIMESTAMP_INVALID_NSEC= 0xffffffff; const DomainId_t DOMAIN_ID_DEFAULT= 0x7fffffff; // // Return codes // const ReturnCode_t RETCODE_OK = 0; const ReturnCode_t RETCODE_ERROR = 1; const ReturnCode_t RETCODE_UNSUPPORTED = 2; const ReturnCode_t RETCODE_BAD_PARAMETER = 3; const ReturnCode_t RETCODE_PRECONDITION_NOT_MET = 4; const ReturnCode_t RETCODE_OUT_OF_RESOURCES = 5; const ReturnCode_t RETCODE_NOT_ENABLED = 6; const ReturnCode_t RETCODE_IMMUTABLE_POLICY = 7; const ReturnCode_t RETCODE_INCONSISTENT_POLICY = 8; const ReturnCode_t RETCODE_ALREADY_DELETED = 9; const ReturnCode_t RETCODE_TIMEOUT = 10; const ReturnCode_t RETCODE_NO_DATA = 11; const ReturnCode_t RETCODE_ILLEGAL_OPERATION = 12;

// // Status to support listeners and conditions // typedef unsigned long StatusKind; typedef unsigned long StatusMask; // bit-mask StatusKind const StatusKind INCONSISTENT_TOPIC_STATUS = 0x0001 << 0; const StatusKind OFFERED_DEADLINE_MISSED_STATUS = 0x0001 << 1; const StatusKind REQUESTED_DEADLINE_MISSED_STATUS = 0x0001 << 2; const StatusKind OFFERED_INCOMPATIBLE_QOS_STATUS = 0x0001 << 5; const StatusKind REQUESTED_INCOMPATIBLE_QOS_STATUS= 0x0001 << 6; const StatusKind SAMPLE_LOST_STATUS = 0x0001 << 7; const StatusKind SAMPLE_REJECTED_STATUS = 0x0001 << 8; const StatusKind DATA_ON_READERS_STATUS = 0x0001 << 9; const StatusKind DATA_AVAILABLE_STATUS = 0x0001 << 10; const StatusKind LIVELINESS_LOST_STATUS = 0x0001 << 11; const StatusKind LIVELINESS_CHANGED_STATUS = 0x0001 << 12; const StatusKind PUBLICATION_MATCHED_STATUS = 0x0001 << 13; const StatusKind SUBSCRIPTION_MATCHED_STATUS = 0x0001 << 14; struct InconsistentTopicStatus {

long total_count;long total_count_change;

}; struct SampleLostStatus {

long total_count;long total_count_change;

}; enum SampleRejectedStatusKind {

NOT_REJECTED,REJECTED_BY_INSTANCE_LIMIT,

600C Reference Guide

Appendices

REJECTED_BY_SAMPLES_LIMIT,REJECTED_BY_SAMPLES_PER_INSTANCE_LIMIT

}; struct SampleRejectedStatus {

long total_count;long total_count_change;SampleRejectedStatusKind last_reason;InstanceHandle_t last_instance_handle;

}; struct LivelinessLostStatus {

long total_count;long total_count_change;

}; struct LivelinessChangedStatus {

long alive_count;long not_alive_count;long alive_count_change;long not_alive_count_change;InstanceHandle_t last_publication_handle;

}; struct OfferedDeadlineMissedStatus {

long total_count;long total_count_change;InstanceHandle_t last_instance_handle;

}; struct RequestedDeadlineMissedStatus {

long total_count;long total_count_change;InstanceHandle_t last_instance_handle;

}; struct QosPolicyCount {

QosPolicyId_t policy_id;long count;

}; typedef sequence<QosPolicyCount> QosPolicyCountSeq; struct OfferedIncompatibleQosStatus {

long total_count;long total_count_change;QosPolicyId_t last_policy_id;QosPolicyCountSeq policies;

}; struct RequestedIncompatibleQosStatus {

long total_count;long total_count_change;QosPolicyId_t last_policy_id;QosPolicyCountSeq policies;

}; struct PublicationMatchedStatus {

long total_count;long total_count_change;

601C Reference Guide

Appendices

long current_count;long current_count_change;InstanceHandle_t last_subscription_handle;

}; struct SubscriptionMatchedStatus {

long total_count;long total_count_change;long current_count;long current_count_change;InstanceHandle_t last_publication_handle;

}; // // Listeners // interface Listener; interface Entity; interface TopicDescription; interface Topic; interface ContentFilteredTopic; interface MultiTopic; interface DataWriter; interface DataReader; interface Subscriber; interface Publisher; typedef sequence<Topic> TopicSeq; typedef sequence<DataReader> DataReaderSeq; interface Listener { }; interface TopicListener : Listener {

voidon_inconsistent_topic( in Topic the_topic, in InconsistentTopicStatus status);

}; interface DataWriterListener : Listener {

voidon_offered_deadline_missed( in DataWriter writer, in OfferedDeadlineMissedStatus status);

voidon_offered_incompatible_qos( in DataWriter writer, in OfferedIncompatibleQosStatus status);

voidon_liveliness_lost( in DataWriter writer, in LivelinessLostStatus status);

voidon_publication_matched( in DataWriter writer,

602C Reference Guide

Appendices

in PublicationMatchedStatus status); }; interface PublisherListener : DataWriterListener { }; interface DataReaderListener : Listener {

voidon_requested_deadline_missed( in DataReader reader, in RequestedDeadlineMissedStatus status);

voidon_requested_incompatible_qos( in DataReader reader, in RequestedIncompatibleQosStatus status);

voidon_sample_rejected( in DataReader reader, in SampleRejectedStatus status);

voidon_liveliness_changed( in DataReader reader, in LivelinessChangedStatus status);

voidon_data_available( in DataReader reader);

voidon_subscription_matched( in DataReader reader, in SubscriptionMatchedStatus status);

voidon_sample_lost( in DataReader reader, in SampleLostStatus status);

}; interface SubscriberListener : DataReaderListener {

voidon_data_on_readers( in Subscriber subs);

}; interface DomainParticipantListener : TopicListener,

PublisherListener, SubscriberListener {

}; // // Conditions // interface Condition {

booleanget_trigger_value();

}; typedef sequence<Condition> ConditionSeq;

603C Reference Guide

Appendices

interface WaitSet {ReturnCode_twait( inout ConditionSeq active_conditions, in Duration_t timeout);ReturnCode_tattach_condition( in Condition cond);ReturnCode_tdetach_condition( in Condition cond);ReturnCode_tget_conditions( inout ConditionSeq attached_conditions);

}; interface GuardCondition : Condition {

ReturnCode_tset_trigger_value( in boolean value);

}; interface StatusCondition : Condition {

StatusMaskget_enabled_statuses();ReturnCode_tset_enabled_statuses( in StatusMask mask);Entityget_entity();

}; // Sample states to support reads typedef unsigned long SampleStateKind; typedef sequence <SampleStateKind> SampleStateSeq; const SampleStateKind READ_SAMPLE_STATE = 0x0001 << 0; const SampleStateKind NOT_READ_SAMPLE_STATE = 0x0001 << 1; // This is a bit-mask SampleStateKind typedef unsigned long SampleStateMask; const SampleStateMask ANY_SAMPLE_STATE = 0xffff; // View states to support reads typedef unsigned long ViewStateKind; typedef sequence<ViewStateKind> ViewStateSeq; const ViewStateKind NEW_VIEW_STATE = 0x0001 << 0; const ViewStateKind NOT_NEW_VIEW_STATE = 0x0001 << 1; // This is a bit-mask ViewStateKind typedef unsigned long ViewStateMask; const ViewStateMask ANY_VIEW_STATE = 0xffff; // Instance states to support reads typedef unsigned long InstanceStateKind; typedef sequence<InstanceStateKind> InstanceStateSeq; const InstanceStateKind ALIVE_INSTANCE_STATE = 0x0001 << 0;

604C Reference Guide

Appendices

const InstanceStateKind NOT_ALIVE_DISPOSED_INSTANCE_STATE = 0x0001 << 1;

const InstanceStateKind NOT_ALIVE_NO_WRITERS_INSTANCE_STATE = 0x0001 << 2;

// This is a bit-mask InstanceStateKind typedef unsigned long InstanceStateMask; const InstanceStateMask ANY_INSTANCE_STATE = 0xffff; const InstanceStateMask NOT_ALIVE_INSTANCE_STATE = 0x006; interface ReadCondition : Condition {

SampleStateMaskget_sample_state_mask();ViewStateMaskget_view_state_mask();InstanceStateMaskget_instance_state_mask();DataReaderget_datareader();

}; interface QueryCondition : ReadCondition {

stringget_query_expression();ReturnCode_tget_query_parameters( inout StringSeq query_parameters);ReturnCode_tset_query_parameters( in StringSeq query_parameters);

}; // // Qos // const string USERDATA_QOS_POLICY_NAME = "UserData"; const string DURABILITY_QOS_POLICY_NAME = "Durability"; const string PRESENTATION_QOS_POLICY_NAME = "Presentation"; const string DEADLINE_QOS_POLICY_NAME = "Deadline"; const string LATENCYBUDGET_QOS_POLICY_NAME = "LatencyBudget"; const string OWNERSHIP_QOS_POLICY_NAME = "Ownership"; const string OWNERSHIPSTRENGTH_QOS_POLICY_NAME=

"OwnershipStrength"; const string LIVELINESS_QOS_POLICY_NAME = "Liveliness"; const string TIMEBASEDFILTER_QOS_POLICY_NAME= "TimeBasedFilter"; const string PARTITION_QOS_POLICY_NAME = "Partition"; const string RELIABILITY_QOS_POLICY_NAME = "Reliability"; const string DESTINATIONORDER_QOS_POLICY_NAME =

"DestinationOrder"; const string HISTORY_QOS_POLICY_NAME = "History"; const string RESOURCELIMITS_QOS_POLICY_NAME= "ResourceLimits"; const string ENTITYFACTORY_QOS_POLICY_NAME = "EntityFactory"; const string WRITERDATALIFECYCLE_QOS_POLICY_NAM=

"WriterDataLifecycle";

605C Reference Guide

Appendices

const string READERDATALIFECYCLE_QOS_POLICY_NAM= "ReaderDataLifecycle";

const string TOPICDATA_QOS_POLICY_NAME = "TopicData"; const string GROUPDATA_QOS_POLICY_NAME = "GroupData"; const string TRANSPORTPRIORITY_QOS_POLICY_NAME=

"TransportPriority"; const string LIFESPAN_QOS_POLICY_NAME = "Lifespan"; const string DURABILITYSERVICE_QOS_POLICY_NAME=

"DurabilityService"; const QosPolicyId_t INVALID_QOS_POLICY_ID = 0; const QosPolicyId_t USERDATA_QOS_POLICY_ID = 1; const QosPolicyId_t DURABILITY_QOS_POLICY_ID = 2; const QosPolicyId_t PRESENTATION_QOS_POLICY_ID = 3; const QosPolicyId_t DEADLINE_QOS_POLICY_ID = 4; const QosPolicyId_t LATENCYBUDGET_QOS_POLICY_ID = 5; const QosPolicyId_t OWNERSHIP_QOS_POLICY_ID = 6; const QosPolicyId_t OWNERSHIPSTRENGTH_QOS_POLICY_ID = 7; const QosPolicyId_t LIVELINESS_QOS_POLICY_ID = 8; const QosPolicyId_t TIMEBASEDFILTER_QOS_POLICY_ID = 9; const QosPolicyId_t PARTITION_QOS_POLICY_ID = 10; const QosPolicyId_t RELIABILITY_QOS_POLICY_ID = 11; const QosPolicyId_t DESTINATIONORDER_QOS_POLICY_ID = 12; const QosPolicyId_t HISTORY_QOS_POLICY_ID = 13; const QosPolicyId_t RESOURCELIMITS_QOS_POLICY_ID = 14; const QosPolicyId_t ENTITYFACTORY_QOS_POLICY_ID = 15; const QosPolicyId_t WRITERDATALIFECYCLE_QOS_POLICY_ID= 16; const QosPolicyId_t READERDATALIFECYCLE_QOS_POLICY_ID= 17; const QosPolicyId_t TOPICDATA_QOS_POLICY_ID = 18; const QosPolicyId_t GROUPDATA_QOS_POLICY_ID = 19; const QosPolicyId_t TRANSPORTPRIORITY_QOS_POLICY_ID = 20; const QosPolicyId_t LIFESPAN_QOS_POLICY_ID = 21; const QosPolicyId_t DURABILITYSERVICE_QOS_POLICY_ID = 22; struct UserDataQosPolicy {

sequence<octet> value; }; struct TopicDataQosPolicy {

sequence<octet> value; }; struct GroupDataQosPolicy {

sequence<octet> value; }; struct TransportPriorityQosPolicy {

long value; }; struct LifespanQosPolicy {

Duration_t duration; }; enum DurabilityQosPolicyKind {

VOLATILE_DURABILITY_QOS,TRANSIENT_LOCAL_DURABILITY_QOS,

606C Reference Guide

Appendices

TRANSIENT_DURABILITY_QOS,PERSISTENT_DURABILITY_QOS

}; struct DurabilityQosPolicy {

DurabilityQosPolicyKind kind; }; enum PresentationQosPolicyAccessScopeKind {

INSTANCE_PRESENTATION_QOS,TOPIC_PRESENTATION_QOS,GROUP_PRESENTATION_QOS

}; struct PresentationQosPolicy {

PresentationQosPolicyAccessScopeKind access_scope;boolean coherent_access;boolean ordered_access;

}; struct DeadlineQosPolicy {

Duration_t period; }; struct LatencyBudgetQosPolicy {

Duration_t duration; }; enum OwnershipQosPolicyKind {

SHARED_OWNERSHIP_QOS,EXCLUSIVE_OWNERSHIP_QOS

}; struct OwnershipQosPolicy {

OwnershipQosPolicyKind kind; }; struct OwnershipStrengthQosPolicy {

long value; }; enum LivelinessQosPolicyKind {

AUTOMATIC_LIVELINESS_QOS,MANUAL_BY_PARTICIPANT_LIVELINESS_QOS,MANUAL_BY_TOPIC_LIVELINESS_QOS

}; struct LivelinessQosPolicy {

LivelinessQosPolicyKind kind;Duration_t lease_duration;

}; struct TimeBasedFilterQosPolicy {

Duration_t minimum_separation; }; struct PartitionQosPolicy {

StringSeq name; }; enum ReliabilityQosPolicyKind {

BEST_EFFORT_RELIABILITY_QOS,RELIABLE_RELIABILITY_QOS

607C Reference Guide

Appendices

}; struct ReliabilityQosPolicy {

ReliabilityQosPolicyKind kind;Duration_t max_blocking_time;boolean synchronous;

}; enum DestinationOrderQosPolicyKind {

BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS,BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS

}; struct DestinationOrderQosPolicy {

DestinationOrderQosPolicyKind kind; }; enum HistoryQosPolicyKind {

KEEP_LAST_HISTORY_QOS,KEEP_ALL_HISTORY_QOS

}; struct HistoryQosPolicy {

HistoryQosPolicyKind kind;long depth;

}; struct ResourceLimitsQosPolicy {

long max_samples;long max_instances;long max_samples_per_instance;

}; struct EntityFactoryQosPolicy {

boolean autoenable_created_entities; }; struct WriterDataLifecycleQosPolicy {

boolean autodispose_unregistered_instances; };

enum DDS_InvalidSampleVisibilityQosPolicyKind { DDS_NO_INVALID_SAMPLES, DDS_MINIMUM_INVALID_SAMPLES, DDS_ALL_INVALID_SAMPLES}struct DDS_InvalidSampleVisibilityQosPolicy { DDS_InvalidSampleVisibilityQosPolicyKind kind;}struct DDS_ReaderDataLifecycleQosPolicy { DDS_Duration_t autopurge_nowriter_samples_delay; DDS_Duration_t autopurge_disposed_samples_delay; DDS_boolean autopurge_dispose_all; DDS_boolean enable_invalid_samples; /* deprecated */ DDS_InvalidSampleVisibilityQosPolicy invalid_sample_visibility;}

struct DurabilityServiceQosPolicy { Duration_t service_cleanup_delay; HistoryQosPolicyKind history_kind;

608C Reference Guide

Appendices

long history_depth; long max_samples; long max_instances; long max_samples_per_instance; }; struct DomainParticipantFactoryQos { EntityFactoryQosPolicy entity_factory; }; struct DomainParticipantQos {

UserDataQosPolicy user_data;EntityFactoryQosPolicy entity_factory;

}; struct TopicQos {

TopicDataQosPolicy topic_data;DurabilityQosPolicy durability;DurabilityServiceQosPolicy durability_service;DeadlineQosPolicy deadline;LatencyBudgetQosPolicy latency_budget;LivelinessQosPolicy liveliness;ReliabilityQosPolicy reliability;DestinationOrderQosPolicy destination_order;HistoryQosPolicy history;ResourceLimitsQosPolicy resource_limits;TransportPriorityQosPolicy transport_priority;LifespanQosPolicy lifespan;OwnershipQosPolicy ownership;

}; struct DataWriterQos {

DurabilityQosPolicy durability;DeadlineQosPolicy deadline;LatencyBudgetQosPolicy latency_budget;LivelinessQosPolicy liveliness;ReliabilityQosPolicy reliability;DestinationOrderQosPolicy destination_order;HistoryQosPolicy history;ResourceLimitsQosPolicy resource_limits;TransportPriorityQosPolicy transport_priority;LifespanQosPolicy lifespan;UserDataQosPolicy user_data;DDS_OwnershipQosPolicy ownership;OwnershipStrengthQosPolicy ownership_strength;WriterDataLifecycleQosPolicy writer_data_lifecycle;

}; struct PublisherQos {

PresentationQosPolicy presentation;PartitionQosPolicy partition;GroupDataQosPolicy group_data;EntityFactoryQosPolicy entity_factory;

}; struct DataReaderQos {

609C Reference Guide

Appendices

DurabilityQosPolicy durability;DeadlineQosPolicy deadline;LatencyBudgetQosPolicy latency_budget;LivelinessQosPolicy liveliness;ReliabilityQosPolicy reliability;DestinationOrderQosPolicy destination_order;HistoryQosPolicy history;ResourceLimitsQosPolicy resource_limits;UserDataQosPolicy user_data;DDS_OwnershipQosPolicy ownership;TimeBasedFilterQosPolicy time_based_filter;ReaderDataLifecycleQosPolicy reader_data_lifecycle;

}; struct SubscriberQos {

PresentationQosPolicy presentation;PartitionQosPolicy partition;GroupDataQosPolicy group_data;EntityFactoryQosPolicy entity_factory;

}; // struct ParticipantBuiltinTopicData {

BuiltinTopicKey_t key;UserDataQosPolicy user_data;

}; struct TopicBuiltinTopicData {

BuiltinTopicKey_t key;string name;string type_name;DurabilityQosPolicy durability;DeadlineQosPolicy deadline;LatencyBudgetQosPolicy latency_budget;LivelinessQosPolicy liveliness;ReliabilityQosPolicy reliability;TransportPriorityQosPolicy transport_priority;LifespanQosPolicy lifespan;DestinationOrderQosPolicy destination_order;HistoryQosPolicy history;ResourceLimitsQosPolicy resource_limits;OwnershipQosPolicy ownership;TopicDataQosPolicy topic_data;

}; struct PublicationBuiltinTopicData {

BuiltinTopicKey_t key;BuiltinTopicKey_t participant_key;string topic_name;string type_name;DurabilityQosPolicy durability;DeadlineQosPolicy deadline;LatencyBudgetQosPolicy latency_budget;LivelinessQosPolicy liveliness;

610C Reference Guide

Appendices

ReliabilityQosPolicy reliability;LifespanQosPolicy lifespan;UserDataQosPolicy user_data;OwnershipStrengthQosPolicy ownership_strength;PresentationQosPolicy presentation;PartitionQosPolicy partition;TopicDataQosPolicy topic_data;GroupDataQosPolicy group_data;

}; struct SubscriptionBuiltinTopicData {

BuiltinTopicKey_t key;BuiltinTopicKey_t participant_key;string topic_name;string type_name;DurabilityQosPolicy durability;DeadlineQosPolicy deadline;LatencyBudgetQosPolicy latency_budget;LivelinessQosPolicy liveliness;ReliabilityQosPolicy reliability;DestinationOrderQosPolicy destination_order;UserDataQosPolicy user_data;TimeBasedFilterQosPolicy time_based_filter;PresentationQosPolicy presentation;PartitionQosPolicy partition;TopicDataQosPolicy topic_data;GroupDataQosPolicy group_data;

}; // interface Entity { // ReturnCode_t // set_qos( // in EntityQos qos); // // ReturnCode_t // get_qos( // inout EntityQos qos); // // ReturnCode_t // set_listener( // in Listener l, // in StatusMask mask); // // Listener // get_listener();

ReturnCode_tenable();StatusConditionget_statuscondition();StatusMaskget_status_changes();

611C Reference Guide

Appendices

}; // interface DomainParticipant : Entity { // Factory interfaces

Publishercreate_publisher( in PublisherQos qos, in PublisherListener a_listener, in StatusMask mask);ReturnCode_tdelete_publisher( in Publisher p);Subscribercreate_subscriber( in SubscriberQos qos, in SubscriberListener a_listener, in StatusMask mask);ReturnCode_tdelete_subscriber( in Subscriber s);Subscriberget_builtin_subscriber();Topiccreate_topic( in string topic_name, in string type_name, in TopicQos qos, in TopicListener a_listener, in StatusMask mask);ReturnCode_tdelete_topic( in Topic a_topic);Topicfind_topic( in string topic_name, in Duration_t timeout);TopicDescriptionlookup_topicdescription( in string name);ContentFilteredTopiccreate_contentfilteredtopic( in string name, in Topic related_topic, in string filter_expression, in StringSeq expression_parameters);ReturnCode_tdelete_contentfilteredtopic( in ContentFilteredTopic a_contentfilteredtopic);MultiTopiccreate_multitopic(

612C Reference Guide

Appendices

in string name, in string type_name, in string subscription_expression, in StringSeq expression_parameters);ReturnCode_tdelete_multitopic( in MultiTopic a_multitopic);ReturnCode_tdelete_contained_entities();ReturnCode_tset_qos( in DomainParticipantQos qos);ReturnCode_tget_qos( inout DomainParticipantQos qos);ReturnCode_tset_listener( in DomainParticipantListener a_listener, in StatusMask mask);DomainParticipantListenerget_listener();ReturnCode_tignore_participant( in InstanceHandle_t handle);ReturnCode_tignore_topic( in InstanceHandle_t handle);ReturnCode_tignore_publication( in InstanceHandle_t handle);ReturnCode_tignore_subscription( in InstanceHandle_t handle);DomainId_tget_domain_id();ReturnCode_tassert_liveliness();ReturnCode_tset_default_publisher_qos( in PublisherQos qos);ReturnCode_tget_default_publisher_qos( inout PublisherQos qos);ReturnCode_tset_default_subscriber_qos( in SubscriberQos qos);ReturnCode_tget_default_subscriber_qos( inout SubscriberQos qos);ReturnCode_t

613C Reference Guide

Appendices

set_default_topic_qos( in TopicQos qos);ReturnCode_tget_default_topic_qos( inout TopicQos qos);

booleancontains_entity( in InstanceHandle_t a_handle);ReturnCode_tget_current_time( inout Time_t current_time);

}; interface DomainParticipantFactory { // // DomainParticipantFactory // get_instance(); //

DomainParticipantcreate_participant( in DomainId_t domainId, in DomainParticipantQos qos, in DomainParticipantListener a_listener, in StatusMask mask);ReturnCode_tdelete_participant( in DomainParticipant a_participant);DomainParticipantlookup_participant( in DomainId_t domainId);ReturnCode_tset_default_participant_qos( in DomainParticipantQos qos);ReturnCode_tget_default_participant_qos( inout DomainParticipantQos qos);

ReturnCode_t set_qos( in DomainParticipantFactoryQos qos);ReturnCode_tget_qos( inout DomainParticipantFactoryQos qos);ReturnCode_tdelete_domain (in Domain a_domain);Domainlookup_domain (in DomainId_t domainId);ReturnCode_t create_persistent_snapshot(

614C Reference Guide

Appendices

in string partition_expression, in string topic_expression, in string URI);ReturnCode_t

delete_contained_entities(); }; interface TypeSupport { // ReturnCode_t // register_type( // in DomainParticipant domain, // in string type_name); // // string // get_type_name(); }; // interface TopicDescription {

stringget_type_name();

stringget_name();

DomainParticipantget_participant();

}; interface Topic : Entity, TopicDescription {

ReturnCode_tset_qos( in TopicQos qos);ReturnCode_t

get_qos( inout TopicQos qos);ReturnCode_t

set_listener( in TopicListener a_listener, in StatusMask mask);TopicListener_ptrget_listener();// Access the statusReturnCode_tget_inconsistent_topic_status( inout InconsistentTopicStatus a_status);

}; interface ContentFilteredTopic : TopicDescription {

stringget_filter_expression();ReturnCode_tget_expression_parameters( inout StringSeq expression_parameters);ReturnCode_tset_expression_parameters(

615C Reference Guide

Appendices

in StringSeq expression_parameters);Topicget_related_topic();

}; interface MultiTopic : TopicDescription {

stringget_subscription_expression();ReturnCode_tget_expression_parameters( inout StringSeq expression_parameters);ReturnCode_tset_expression_parameters( in StringSeq expression_parameters);

}; // interface Publisher : Entity {

DataWritercreate_datawriter( in Topic a_topic, in DataWriterQos qos, in DataWriterListener a_listener, in StatusMask mask);ReturnCode_tdelete_datawriter( in DataWriter a_datawriter);DataWriterlookup_datawriter( in string topic_name);ReturnCode_tdelete_contained_entities();ReturnCode_tset_qos( in PublisherQos qos);ReturnCode_tget_qos( inout PublisherQos qos);ReturnCode_tset_listener( in PublisherListener a_listener, in StatusMask mask);PublisherListenerget_listener();ReturnCode_tsuspend_publications();ReturnCode_tresume_publications();ReturnCode_tbegin_coherent_changes();ReturnCode_tend_coherent_changes();

616C Reference Guide

Appendices

ReturnCode_twait_for_acknowledgments( in Duration_t max_wait);DomainParticipantget_participant();ReturnCode_tset_default_datawriter_qos( in DataWriterQos qos);ReturnCode_tget_default_datawriter_qos( inout DataWriterQos qos);ReturnCode_tcopy_from_topic_qos( inout DataWriterQos a_datawriter_qos, in TopicQos a_topic_qos);

}; interface DataWriter : Entity { // InstanceHandle_t // register_instance( // in Data instance_data); // // InstanceHandle_t // register_instance_w_timestamp( // in Data instance_data, // in Time_t source_timestamp); // // ReturnCode_t // unregister_instance( // in Data instance_data, // in InstanceHandle_t handle); // // ReturnCode_t // unregister_instance_w_timestamp( // in Data instance_data, // in InstanceHandle_t handle, // in Time_t source_timestamp); // // ReturnCode_t // write( // in Data instance_data, // in InstanceHandle_t handle); // // ReturnCode_t // write_w_timestamp( // in Data instance_data, // in InstanceHandle_t handle, // in Time_t source_timestamp); // // ReturnCode_t // dispose(

617C Reference Guide

Appendices

// in Data instance_data, // in InstanceHandle_t instance_handle); // // ReturnCode_t // dispose_w_timestamp( // in Data instance_data, // in InstanceHandle_t instance_handle, // in Time_t source_timestamp); // // ReturnCode_t // get_key_value( // inout Data key_holder, // in InstanceHandle_t handle); // // InstanceHandle_t lookup_instance( // in Data instance_data);

ReturnCode_tset_qos( in DataWriterQos qos);ReturnCode_tget_qos( inout DataWriterQos qos);ReturnCode_tset_listener( in DataWriterListener a_listener, in StatusMask mask);DataWriterListenerget_listener();Topicget_topic();Publisherget_publisher();ReturnCode_twait_for_acknowledgments( in Duration_t max_wait);// Access the statusReturnCode_tget_liveliness_lost_status( inout LivelinessLostStatus status);ReturnCode_tget_offered_deadline_missed_status( inout OfferedDeadlineMissedStatus status);ReturnCode_tget_offered_incompatible_qos_status( inout OfferedIncompatibleQosStatus status);ReturnCode_tget_publication_matched_status( inout PublicationMatchedStatus status);ReturnCode_t

assert_liveliness();

618C Reference Guide

Appendices

ReturnCode_tget_matched_subscriptions(

inout InstanceHandleSeq subscription_handles);ReturnCode_t

get_matched_subscription_data( inout SubscriptionBuiltinTopicData subscription_data, in InstanceHandle_t subscription_handle);

}; // interface Subscriber : Entity {

DataReadercreate_datareader( in TopicDescription a_topic, in DataReaderQos qos, in DataReaderListener a_listener, in StatusMask mask);ReturnCode_tdelete_datareader( in DataReader a_datareader);ReturnCode_tdelete_contained_entities();DataReaderlookup_datareader( in string topic_name);ReturnCode_tget_datareaders( inout DataReaderSeq readers, in SampleStateMask sample_states, in ViewStateMask view_states, in InstanceStateMask instance_states);ReturnCode_tnotify_datareaders();ReturnCode_t

set_qos( in SubscriberQos qos);ReturnCode_t

get_qos( inout SubscriberQos qos);ReturnCode_tset_listener( in SubscriberListener a_listener, in StatusMask mask);SubscriberListenerget_listener();ReturnCode_tbegin_access();ReturnCode_tend_access();DomainParticipantget_participant();

619C Reference Guide

Appendices

ReturnCode_tset_default_datareader_qos( in DataReaderQos qos);ReturnCode_tget_default_datareader_qos( inout DataReaderQos qos);ReturnCode_tcopy_from_topic_qos( inout DataReaderQos a_datareader_qos, in TopicQos a_topic_qos);

}; interface DataReader : Entity { // ReturnCode_t // read( // inout DataSeq data_values, // inout SampleInfoSeq info_seq, // in long max_samples, // in SampleStateMask sample_states, // in ViewStateMask view_states, // in InstanceStateMask instance_states); // // ReturnCode_t // take( // inout DataSeq data_values, // inout SampleInfoSeq info_seq, // in long max_samples, // in SampleStateMask sample_states, // in ViewStateMask view_states, // in InstanceStateMask instance_states); // // ReturnCode_t // read_w_condition( // inout DataSeq data_values, // inout SampleInfoSeq info_seq, // in long max_samples, // in ReadCondition a_condition); // // ReturnCode_t // take_w_condition( // inout DataSeq data_values, // inout SampleInfoSeq info_seq, // in long max_samples, // in ReadCondition a_condition); // // ReturnCode_t // read_next_sample( // inout Data data_values, // inout SampleInfo sample_info); // // ReturnCode_t

620C Reference Guide

Appendices

// take_next_sample( // inout Data data_values, // inout SampleInfo sample_info); // // ReturnCode_t // read_instance( // inout DataSeq data_values, // inout SampleInfoSeq info_seq, // in long max_samples, // in InstanceHandle_t a_handle, // in SampleStateMask sample_states, // in ViewStateMask view_states, // in InstanceStateMask instance_states); // // ReturnCode_t // take_instance( // inout DataSeq data_values, // inout SampleInfoSeq info_seq, // in long max_samples, // in InstanceHandle_t a_handle, // in SampleStateMask sample_states, // in ViewStateMask view_states, // in InstanceStateMask instance_states); // // ReturnCode_t // read_next_instance( // inout DataSeq data_values, // inout SampleInfoSeq info_seq, // in long max_samples, // in InstanceHandle_t a_handle, // in SampleStateMask sample_states, // in ViewStateMask view_states, // in InstanceStateMask instance_states); // // ReturnCode_t // take_next_instance( // inout DataSeq data_values, // inout SampleInfoSeq info_seq, // in long max_samples, // in InstanceHandle_t a_handle, // in SampleStateMask sample_states, // in ViewStateMask view_states, // in InstanceStateMask instance_states); // // ReturnCode_t // read_next_instance_w_condition( // inout DataSeq data_values, // inout SampleInfoSeq info_seq, // in long max_samples, // in InstanceHandle_t a_handle,

621C Reference Guide

Appendices

// in ReadCondition a_condition); // // ReturnCode_t // take_next_instance_w_condition( // inout DataSeq data_values, // inout SampleInfoSeq info_seq, // in long max_samples, // in InstanceHandle_t a_handle, // in ReadCondition a_condition); // // ReturnCode_t // return_loan( // inout DataSeq data_values, // inout SampleInfoSeq info_seq); // // ReturnCode_t // get_key_value( // inout Data key_holder, // in InstanceHandle_t handle); // // InstanceHandle_t // lookup_instance( // in Data instance);

ReadConditioncreate_readcondition( in SampleStateMask sample_states, in ViewStateMask view_states, in InstanceStateMask instance_states);QueryConditioncreate_querycondition( in SampleStateMask sample_states, in ViewStateMask view_states, in InstanceStateMask instance_states, in string query_expression, in StringSeq query_parameters);ReturnCode_tdelete_readcondition( in ReadCondition a_condition);ReturnCode_tdelete_contained_entities();ReturnCode_tset_qos( in DataReaderQos qos);ReturnCode_tget_qos( inout DataReaderQos qos);ReturnCode_tset_listener( in DataReaderListener a_listener, in StatusMask mask);

622C Reference Guide

Appendices

DataReaderListenerget_listener();TopicDescriptionget_topicdescription();Subscriberget_subscriber();ReturnCode_tget_sample_rejected_status( inout SampleRejectedStatus status);ReturnCode_tget_liveliness_changed_status( inout LivelinessChangedStatus status);ReturnCode_tget_requested_deadline_missed_status( inout RequestedDeadlineMissedStatus status);ReturnCode_tget_requested_incompatible_qos_status( inout RequestedIncompatibleQosStatus status);ReturnCode_tget_subscription_matched_status( inout SubscriptionMatchedStatus status);ReturnCode_tget_sample_lost_status( inout SampleLostStatus status);ReturnCode_twait_for_historical_data( in Duration_t max_wait);ReturnCode_tget_matched_publications( inout InstanceHandleSeq publication_handles);ReturnCode_tget_matched_publication_data( inout PublicationBuiltinTopicData publication_data, in InstanceHandle_t publication_handle);

}; struct SampleInfo {

SampleStateKind sample_state;ViewStateKind view_state;InstanceStateKind instance_state;Time_t source_timestamp;InstanceHandle_t instance_handle;BuiltinTopicKey_t publication_handle;long disposed_generation_count;long no_writers_generation_count;long sample_rank;long generation_rank;long absolute_generation_rank;boolean valid_data;

}; typedef sequence<SampleInfo> SampleInfoSeq;

623C Reference Guide

Appendices

};Foo.idl // Implied IDL for type "Foo" // Example user defined structure struct Foo {

long dummy; }; typedef sequence<Foo> FooSeq; #include "dds_dcps.idl" interface FooTypeSupport : DDS::TypeSupport {

DDS::ReturnCode_tregister_type( in DDS::DomainParticipant participant, in string type_name);stringget_type_name();

}; interface FooDataWriter : DDS::DataWriter {

DDS::InstanceHandle_tregister_instance( in Foo instance_data);DDS::InstanceHandle_tregister_instance_w_timestamp( in Foo instance_data, in DDS::InstanceHandle_t handle, in DDS::Time_t source_timestamp);DDS::ReturnCode_tunregister_instance( in Foo instance_data, in DDS::InstanceHandle_t handle);DDS::ReturnCode_tunregister_instance_w_timestamp( in Foo instance_data, in DDS::InstanceHandle_t handle, in DDS::Time_t source_timestamp);DDS::ReturnCode_twrite( in Foo instance_data, in DDS::InstanceHandle_t handle);DDS::ReturnCode_twrite_w_timestamp( in Foo instance_data, in DDS::InstanceHandle_t handle, in DDS::Time_t source_timestamp);DDS::ReturnCode_tdispose( in Foo instance_data, in DDS::InstanceHandle_t instance_handle);DDS::ReturnCode_tdispose_w_timestamp(

624C Reference Guide

Appendices

in Foo instance_data, in DDS::InstanceHandle_t instance_handle, in DDS::Time_t source_timestamp);DDS::ReturnCode_tget_key_value( inout Foo key_holder, in DDS::InstanceHandle_t handle);DDS::InstanceHandle_tlookup_instance( in Foo instance_data);

}; interface FooDataReader : DDS::DataReader {

DDS::ReturnCode_tread( inout FooSeq data_values, inout DDS::SampleInfoSeq info_seq, in long max_samples, in DDS::SampleStateMask sample_states, in DDS::ViewStateMask view_states, in DDS::InstanceStateMask instance_states);DDS::ReturnCode_ttake( inout FooSeq data_values, inout DDS::SampleInfoSeq info_seq, in long max_samples, in DDS::SampleStateMask sample_states, in DDS::ViewStateMask view_states, in DDS::InstanceStateMask instance_states);DDS::ReturnCode_tread_w_condition( inout FooSeq data_values, inout DDS::SampleInfoSeq info_seq, in long max_samples, in DDS::ReadCondition a_condition);DDS::ReturnCode_ttake_w_condition( inout FooSeq data_values, inout DDS::SampleInfoSeq info_seq, in long max_samples, in DDS::ReadCondition a_condition);DDS::ReturnCode_tread_next_sample( inout Foo data_values, inout DDS::SampleInfo sample_info);DDS::ReturnCode_ttake_next_sample( inout Foo data_values, inout DDS::SampleInfo sample_info);DDS::ReturnCode_tread_instance(

625C Reference Guide

Appendices

inout FooSeq data_values, inout DDS::SampleInfoSeq info_seq, in long max_samples, in DDS::InstanceHandle_t a_handle, in DDS::SampleStateMask sample_states, in DDS::ViewStateMask view_states, in DDS::InstanceStateMask instance_states);DDS::ReturnCode_ttake_instance( inout FooSeq data_values, inout DDS::SampleInfoSeq info_seq, in long max_samples, in DDS::InstanceHandle_t a_handle, in DDS::SampleStateMask sample_states, in DDS::ViewStateMask view_states, in DDS::InstanceStateMask instance_states);DDS::ReturnCode_tread_next_instance( inout FooSeq data_values, inout DDS::SampleInfoSeq info_seq, in long max_samples, in DDS::InstanceHandle_t a_handle, in DDS::SampleStateMask sample_states, in DDS::ViewStateMask view_states, in DDS::InstanceStateMask instance_states);DDS::ReturnCode_ttake_next_instance( inout FooSeq data_values, inout DDS::SampleInfoSeq info_seq, in long max_samples, in DDS::InstanceHandle_t a_handle, in DDS::SampleStateMask sample_states, in DDS::ViewStateMask view_states, in DDS::InstanceStateMask instance_states);DDS::ReturnCode_tread_next_instance_w_condition( inout FooSeq data_values, inout DDS::SampleInfoSeq info_seq, in long max_samples, in DDS::InstanceHandle_t a_handle, in DDS::ReadCondition a_condition);DDS::ReturnCode_ttake_next_instance_w_condition( inout FooSeq data_values, inout DDS::SampleInfoSeq info_seq, in long max_samples, in DDS::InstanceHandle_t a_handle, in DDS::ReadCondition a_condition);DDS::ReturnCode_treturn_loan(

626C Reference Guide

Appendices

inout FooSeq data_values, inout DDS::SampleInfoSeq info_seq);DDS::ReturnCode_tget_key_value( inout Foo key_holder, in DDS::InstanceHandle_t handle);DDS::InstanceHandle_tlookup_instance( in Foo instance);

};

627C Reference Guide

Appendices

628C Reference Guide

Appendix

D SampleStates, ViewStates and InstanceStates

Data is made available to the application by the following operations onDDS_DataReader o b j e c t s : DDS_DataReader_read a n dDDS_DataReader_take opera t ions . The genera l semant ics o f theDDS_DataReader_read operations is that the application only gets access to thematching data; the data remain available in the Data Distribution Services and canbe read again. The semantics of the DDS_DataReader_take operations is that thedata is not available in the Data Distribution Service; that data will no longer beaccessible to the DDS_DataReader. Consequently, it is possible for aDDS_DataReader to access the same sample multiple times but only if all previousaccesses were DDS_DataReader_read operations.Each of these operations returns an ordered collection of Data values andassociated DDS_SampleInfo objects. Each data value represents an atom of datainformation (i.e., a value for one instance). This collection may contain samplesrelated to the same or different instances (identified by the key). Multiple samplescan refer to the same instance if the settings of the DDS_HistoryQosPolicy allowfor it.

SampleInfo ClassDDS_SampleInfo is the information that accompanies each sample that is ‘read’ or‘taken’. It contains, among others, the following information:• The sample_state (DDS_READ_SAMPLE_STATE or

DDS_NOT_READ_SAMPLE_STATE);• The view_state, (DDS_NEW_VIEW_STATE or DDS_NOT_NEW_VIEW_STATE);• The instance_state (DDS_ALIVE_INSTANCE_STATE,DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE orDDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE).

sample_stateFor each sample, the Data Distribution Service internally maintains asample_state specific to each DDS_DataReader. The sample_state caneither be DDS_READ_SAMPLE_STATE or DDS_NOT_READ_SAMPLE_STATE.

629C Reference Guide

Appendices

• DDS_READ_SAMPLE_STATE indicates that the DDS_DataReader has alreadyaccessed that sample by means of DDS_DataReader_read. Had the sample beenaccessed by DDS_DataReader_take it would no longer be available to theDDS_DataReader;

• DDS_NOT_READ_SAMPLE_STATE indicates that the DDS_DataReader has notaccessed that sample before.

Figure 20: State Chart of the sample_state for a Single Sample

State per SampleThe sample_state available in the DDS_SampleInfo reflect the sample_stateof each sample. The sample_state can be different for all samples in the returnedcollection that refer to the same instance.

new sample received

take /

read

read

READ_SAMPLE_STATE

take /

(first time seen)

NOT_READ_SAMPLE_STATE

sample is “overwritten”

sample is “overwritten”

630C Reference Guide

Appendices

instance_stateFor each instance the Data Distribution Service internally maintains aninstance_state. The instance_state can be:• DDS_ALIVE_INSTANCE_STATE indicates that:

- samples have been received for the instance - there are live DDS_DataWriter objects writing the instance - the instance has not been explicitly disposed of (or else samples have been

received after it was disposed of)• DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE indicates the instance was

disposed of by a DDS_DataWriter either explicitly by means of theDDS_DataWriter_dispose operation or implicitly in case theautodispose_unregistered_instances field of theWriterDataLyfecycleQosPolicy equals TRUE when the instance getsunregistered (see Section 3.1.3.23, DDS_WriterDataLifecycleQosPolicy), and nonew samples for that instance have been written afterwards.

• DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE indicates the instance hasbeen declared as not-alive by the DDS_DataReader because it detected that thereare no live DDS_DataWriter objects writing that instance.

DDS_OwnershipQosPolicyThe precise events that cause the instance_state to change depends on thesetting of the DDS_OwnershipQosPolicy:• If DDS_OwnershipQosPolicy is set to DDS_EXCLUSIVE_OWNERSHIP_QOS,

then the instance_state becomesDDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE only if the DDS_DataWriterthat “owns” the instance explicitly disposes of it. The instance_state becomesDDS_ALIVE_INSTANCE_STATE again only if the DDS_DataWriter that ownsthe instance writes it;

• If DDS_OwnershipQosPolicy is set to DDS_SHARED_OWNERSHIP_QOS, thenthe instance_state becomesDDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE if any DDS_DataWriterexplicitly disposes of the instance. The instance_state becomesDDS_ALIVE_INSTANCE_STATE as soon as any DDS_DataWriter writes theinstance again.

631C Reference Guide

Appendices

Figure 21: State Chart of the instance_state for a Single Instance

SnapshotThe instance_state available in the DDS_SampleInfo is a snapshot of theinstance_state of the instance at the time the collection was obtained (i.e. at thetime DDS_DataReader_read or DDS_DataReader_take was called). Theinstance_state is therefore the same for all samples in the returned collectionthat refer to the same instance.

view_stateFor each instance (identified by the key), the Data Distribution Service internallymaintains a view_state relative to each DDS_DataReader. The view_statecan either be DDS_NEW_VIEW_STATE or DDS_NOT_NEW_VIEW_STATE.

NOT_ALIVE_NO_WRITERS_INSTANCE_STATE

ALIVE_INSTANCE_STATE

NOT_ALIVE_DISPOSED_INSTANCE_STATE

sample received

sample for 'never seen'

no "live"instance disposed

sample received/

[no samples in the DDS_DataReader [no samples in

"live" DDS_DataWriter detected/

DDS_DataWritersof by DDS_DataWriter

the DDS_DataReader] && no "live" DDS_DataWriters]

instance received/

632C Reference Guide

Appendices

• DDS_NEW_VIEW_STATE indicates that either this is the first time that theDDS_DataReader has ever accessed samples of that instance, or else that theDDS_DataReader has accessed previous samples of the instance, but the instancehas since been reborn (i.e. becomes not-alive and then alive again);

• DDS_NOT_NEW_VIEW_STATE indicates that the DDS_DataReader has alreadyaccessed samples of the same instance and that the instance has not been rebornsince.

Figure 22: State Chart of the view_state for a Single Instance

SnapshotThe view_state available in the DDS_SampleInfo is a snapshot of view_stateof the instance relative to the DDS_DataReader used to access the samples at thetime the collection was obtained (i.e. at the time DDS_DataReader_read orDDS_DataReader_take was called). The view_state is therefore the same forall samples in the returned collection that refer to the same instance.

sample for 'never seen'instance received/

NEW_VIEW_STATE

[instance_state == ALIVE_INSTANCE_STATE] [instance_state == NOT_ALIVE_INSTANCE_STATE]

sample received

read/take

read/take

NOT_NEW_VIEW_STATE

633C Reference Guide

Appendices

State MasksState Definitions

All states are available as a constant. These convenience constants can be used tocreate a bit-mask (e.g. to be used as operation parameters) by performing an AND orOR operation. They can also be used for testing whether a state is set.The sample state definitions indicates whether or not the matching data sample hasalready been read:• DDS_READ_SAMPLE_STATE: sample has already been read;• DDS_NOT_READ_SAMPLE_STATE: sample has not been read.The view state definitions indicates whether the DDS_DataReader has already seensamples for the most-current generation of the related instance:• DDS_NEW_VIEW_STATE: all samples of this instance are new;• DDS_NOT_NEW_VIEW_STATE: some or all samples of this instance are not new.The instance state definitions indicates whether the instance is currently in existenceor, if it has been disposed of, the reason why it was disposed of:• DDS_ALIVE_INSTANCE_STATE: this instance is currently in existence;• DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE: this instance was disposed of

by a DDS_DataWriter;• DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE: the instance has been

disposed of by the DDS_DataReader because none of the DDS_DataWriterobjects currently “alive” (according to the DDS_LivelinessQosPolicy) arewriting the instance.

Pre-defined Bit Mask DefinitionsFor convenience, some pre-defined bit-masks are available as a constant definition.These bit-mask constants can be used where a state bit-mask is required. They canalso be used for testing whether certain bits are set.The sample state bit-mask definition selects both sample states:• DDS_ANY_SAMPLE_STATE: either the sample has already been read or not read;The view state bit-mask definition selects both view states:• DDS_ANY_VIEW_STATE: either the sample has already been seen or not seen;The instance state bit-mask definitions selects a combination of instance states:• DDS_NOT_ALIVE_INSTANCE_STATE: this instance was disposed of by aDDS_DataWriter or the DDS_DataReader;

• DDS_ANY_INSTANCE_STATE: this instance is either in existence or not inexistence.

634C Reference Guide

Appendices

Operations Concerning StatesThe application accesses data by means of the operations DDS_DataReader_reador DDS_DataReader_take on the DDS_DataReader. These operations return anordered collection of DDS_DataSamples consisting of a DDS_SampleInfo partand a Data part. The way the Data Distribution Service builds this collection (i.e.,the data-samples that are parts of the list as well as their order) depends onQosPolicy settings set on the DDS_DataReader and the DDS_Subscriber, aswell as the source timestamp of the samples and the parameters passed to theDDS_DataReader_read/DDS_DataReader_take operations, namely:• the desired sample states (i.e., DDS_READ_SAMPLE_STATE,DDS_NOT_READ_SAMPLE_STATE, or DDS_ANY_SAMPLE_STATE);

• the desired view states (i.e., DDS_NEW_VIEW_STATE,DDS_NOT_NEW_VIEW_STATE, or DDS_ANY_VIEW_STATE);

• the desired instance states (DDS_ALIVE_INSTANCE_STATE,DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE,DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE,DDS_NOT_ALIVE_INSTANCE_STATE, or DDS_ANY_INSTANCE_STATE).

The DDS_DataReader_read and DDS_DataReader_take operations arenon-blocking and just deliver what is currently available that matches the specifiedstates.On output, the collection of Data values and the collection of DDS_SampleInfostructures are of the same length and are in a one-to-one correspondence. EachDDS_SampleInfo provides information, such as the source_timestamp, thesample_state, view_state, and instance_state, etc., about the matchingsample.Some elements in the returned collection may not have valid data. If theinstance_state i n t h e DDS_SampleInfo i sDDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE o rDDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE, then the last sample for thatinstance in the collection, that is, the one whose DDS_SampleInfo hassample_rank==0 does not contain valid data. Samples that contain no data do notcount towards the limits imposed by the DDS_ResourceLimitsQosPolicy.

readThe act of reading a sample sets its sample_state to DDS_READ_SAMPLE_STATE.If the sample belongs to the most recent generation of the instance, it will also setthe view_state of the instance to DDS_NOT_NEW_VIEW_STATE. It will not affectthe instance_state of the instance.

635C Reference Guide

Appendices

takeThe act of taking a sample removes it from the DDS_DataReader so it cannot be‘read’ or ‘taken’ again. If the sample belongs to the most recent generation of thei n s t a n c e , i t w i l l a l s o s e t t h e view_state o f t h e i n s t a n c e t oDDS_NOT_NEW_VIEW_STATE. It will not affect the instance_state of theinstance.

read_w_conditionIn case the DDS_ReadCondition is a ‘plain’ DDS_ReadCondition and not thespecialized DDS_QueryCondition, the operation is equivalent to callingDDS_DataReader_read and passing as sample_states, view_states andinstance_states the value of the corresponding at t r ibutes in theDDS_ReadCondition. Using this operation the application can avoid repeating thesame parameters specified when creating the DDS_ReadCondition.

take_w_conditionThe act of taking a sample removes it from the DDS_DataReader so it cannot be‘read’ or ‘taken’ again. If the sample belongs to the most recent generation of thei n s t a n c e , i t w i l l a l s o s e t t h e view_state o f t h e i n s t a n c e t oDDS_NOT_NEW_VIEW_STATE. It will not affect the instance_state of theinstance.In case the DDS_ReadCondition is a ‘plain’ DDS_ReadCondition and not thespecialized DDS_QueryCondition, the operation is equivalent to callingDDS_DataReader_take and passing as sample_states, view_states andinstance_states the value of the corresponding at t r ibutes in theDDS_ReadCondition. Using this operation the application can avoid repeating thesame parameters specified when creating the DDS_ReadCondition.

read_next_sampleThe DDS_DataReader_read_next_sample operation is semantically equivalentto the DDS_DataReader_read operation where the input Data sequence hasmax_len=1, the sample_states=DDS_NOT_READ_SAMPLE_STATE, theview_states=DDS_ANY_VIEW_STATE, and theinstance_states=DDS_ANY_INSTANCE_STATE.

take_next_sampleThe DDS_DataReader_take_next_sample operation is semantically equivalentto the DDS_DataReader_take operation where the input sequence hasmax_len=1, the sample_states=DDS_NOT_READ_SAMPLE_STATE, theview_states=DDS_ANY_VIEW_STATE, and theinstance_states=DDS_ANY_INSTANCE_STATE.

636C Reference Guide

Appendices

read_instanceThe act of reading a sample sets its sample_state to DDS_READ_SAMPLE_STATE.If the sample belongs to the most recent generation of the instance, it will also setthe view_state of the instance to DDS_NOT_NEW_VIEW_STATE. It will not affectthe instance_state of the instance.

take_instanceThe act of taking a sample removes it from the DDS_DataReader so it cannot be‘read’ or ‘taken’ again. If the sample belongs to the most recent generation of thei n s t a n c e , i t w i l l a l s o s e t t h e view_state o f t h e i n s t a n c e t oDDS_NOT_NEW_VIEW_STATE. It will not affect the instance_state of theinstance.

637C Reference Guide

Appendices

638C Reference Guide

Appendix

E Class InheritanceThis appendix gives an overview of the inheritance relations of the DCPS classes.

Figure 23: DCPS Inheritance

FooDataReader(from Topic-Definition Module)

FooDataWriter(from Topic-Definition Module)

FooTypeSupport(from Topic-Definition Module)

TopicListener

<<Interface>>

TypeSupport(from Topic-Definition Module)

<<Interface>>

TopicDescription(from Topic-Definition Module)

DataReaderListener(from Subscription Module)

<<Interface>> QueryCondition(from Subscription Module)

SampleInfo(from Subscription Module)

SubscriberListener(from Subscription Module)

<<Interface>>

DataWriterListener(from Publication Module)

<<Interface>>

PublisherListener(from Publication Module)

<<Interface>>

GuardCondition(from Infrastructure Module)

Listener(from Infrastructure Module)

<<Interface>>

Status(from Infrastructure Module)

DataWriter(from Publication Module)

Entity(from Infrastructure Module)

DataReader(from Subscription Module)

StatusCondition(from Infrastructure Module)

Condition(from Infrastructure Module)

ReadCondition(from Subscription Module)

WaitSet(from Infrastructure Module)

Publisher(from Publication Module)

Subscriber(from Subscription Module)

Topic(from Topic-Definition Module)

ContentFilteredTopic(from Topic-Definition Module)

MultiTopic(from Topic-Definition Module)

DomainEntity(from Infrastructure Module)

QosPolicy(from Infrastructure Module)

DomainParticipantFactory(from Domain Module)

DomainParticipantListener(from Domain Module)

DomainParticipant(from Domain Module)

639C Reference Guide

Appendices

640C Reference Guide

Appendix

F Listeners, Conditions and Waitsets

Listeners and DDS_Conditions (DDS_Conditions in conjunction withDDS_WaitSets) are two mechanisms that allow the application to be made awareof changes in the communication status. Listeners provide an event-basedmechanism for the Data Distribution Service to asynchronously alert the applicationof the occurrence of relevant status changes. DDS_Conditions in conjunction withDDS_WaitSets provide a state-based mechanism for the Data Distribution Serviceto synchronously communicate the relevant status changes to the application.Both mechanisms are based on the communication statuses associated with anDDS_Entity object. Not all statuses are applicable to all DDS_Entity objects.Which status is applicable to which DDS_Entity object is listed in the next table:

Table 26: Communication Status

DDS_Entity Status Name DescriptionDDS_Topic DDS_INCONSISTENT_TOPIC_STATUS Another DDS_Topic exists with the same

name but with different characteristics.DDS_Subscriber DDS_DATA_ON_READERS_STATUS New information is available.

641C Reference Guide

Appendices

The statuses may be classified in:• read communication statuses: i.e., those that are related to arrival of data, namelyDDS_DATA_ON_READERS and DDS_DATA_AVAILABLE

• plain communication statuses: i.e., all the others.

DDS_DataReader DDS_SAMPLE_REJECTED_STATUS A (received) sample has been rejected.DDS_LIVELINESS_CHANGED_STATUS T h e l i v e l i n e s s o f o n e o r m o r e

DDS_DataWriter objects, that werew r i t i n g i n s t a n c e s r e a d t h r o u g h t h eDDS_DataReader objects has changed.Some DDS_DataWriter object havebecome “alive” or “not alive”.

DDS_REQUESTED_ DEADLINE_MISSED_STATUS

The deadline that the DDS_DataReaderw a s e x p e c t i n g t h r o u g h i t sDDS_DeadlineQosPolicy was notrespected for a specific instance.

DDS_REQUESTED_ INCOMPATIBLE_QOS_STATUS

A QosPolicy setting was incompatible withwhat is offered.

DDS_DATA_AVAILABLE_STATUS New information is available.DDS_SAMPLE_LOST_STATUS A sample has been lost (never received).DDS_SUBSCRIPTION_ MATCHED_STATUS

The DDS_DataReader has found aDDS_DataWriter that matches theZWDDS_Topic and has compatible QoS.

DDS_DataWriter DDS_LIVELINESS_LOST_STATUS The liveliness that the DDS_DataWriterh a s c o m m i t t e d t h r o u g h i t sDDS_LivelinessQosPolicy was notrespected; thus DDS_DataReader objectswill consider the DDS_DataWriter as nolonger “alive”.

DDS_OFFERED_ DEADLINE_MISSED_STATUS

The deadline that the DDS_DataWriterh a s c o m m i t t e d t h r o u g h i t sDDS_DeadlineQosPolicy was notrespected for a specific instance.

DDS_OFFERED_ INCOMPATIBLE_QOS_STATUS

A QosPolicy setting was incompatible withwhat was requested.

DDS_PUBLICATION_ MATCHED_STATUS

T h e DDS_DataWriter h a s f o u n dDDS_DataReader that matches theDDS_Topic and has compatible QoS.

Table 26: Communication Status (Continued)

DDS_Entity Status Name Description

642C Reference Guide

Appendices

For each plain communication status, there is a corresponding status struct. Thein fo rma t ion f rom th i s s t ruc t can be r e t r i eved wi th t he ope ra t ionsget_<status_name>_status . F o r e x a m p l e , t o g e t t h eDDS_INCONSISTENT_TOPIC status (which information is stored in theDDS_InconsistentTopicStatus struct), the application must call the operationDDS_Topic_get_inconsistent_topic_status. A plain communicationstatus can only be read from the DDS_Entity on which it is applicable. For the readcommunication statuses there is no struct available to the application.

Communication Status EventConceptually associated with each DDS_Entity communication status is a logicalStatusChangedFlag. This flag indicates whether that particular communicationstatus has changed since the last time the status was ‘read’ by the application (thereis no actual read-operat ion to read the StatusChangedFlag ) . TheStatusChangedFlag is only conceptually needed to explain the behaviour of aListener, therefore, it is not important whether this flag actually exists. AListener will only be activated when the StatusChangedFlag changes fromFALSE to TRUE (provided the Listener is attached and enabled for this particularstatus). The conditions which cause the StatusChangedFlag to change is slightlydifferent for the plain communication status and the read communication status.For the plain communication status, the StatusChangedFlag flag is initially set toFALSE. It becomes TRUE whenever the plain communication status changes and it isreset to FALSE each time the application accesses the plain communication statusvia the proper get_<status_name>_status operation on the DDS_Entity.The communication status is also reset to FALSE whenever the associatedListener operation is called as the Listener implicitly accesses the status whichis passed as a parameter to the operation. The fact that the status is reset prior toc a l l i n g t h e l i s t e n e r m e a n s t h a t i f t h e a p p l i c a t i o n c a l l s t h eget_<status_name>_status from inside the listener it will see the statusalready reset.An exception to this rule is when the associated Listener is the nil listener, inother word, a listener with value DDS_OBJECT_NIL. Such a listener is treated as aNOOP1 for all statuses activated in its bitmask and the act of calling this 'nil' listenerdoes not reset the corresponding communication statuses.

1. Short for No-Operation, an instruction that peforms nothing at all.

643

C Reference Guide

Appendices

Figure 24: Plain Communication Status State Chart

For example, the value of the StatusChangedFlag associated with theDDS_RequestedDeadlineMissedStatus will become TRUE each time a newde ad l i ne pa s se s (wh ic h i nc r ea se s t h e t o t a l _ c o u n t f i e ld w i t h i nDDS_RequestedDeadlineMissedStatus). The value changes to FALSE whenthe app l i c a t i on acce s se s t he s t a t u s v i a t h e c o r r e s p o n d i n gDDS_DataReader_get_requested_deadline_missed_status operation onthe proper DDS_Entity, or when the the on_requested_deadline_missedoperation on the Listener attached to this DDS_Entity or one its containingentities is invoked.For the read communication status, the StatusChangedFlag flag is initially set toFALSE. It becomes TRUE when data arrives, or when the InstanceState of acontained instance changes. This can be caused by either:• The arrival of the notification that an instance has been disposed by:

- the DDS_DataWriter that owns it if its OwnershipQosPolicyKind =DDS_EXCLUSIVE_OWNERSHIP_QOS

- or by any DDS_DataWriter if its OwnershipQosPolicyKind =DDS_SHARED_OWNERSHIP_QOS.

• The loss of liveliness of the DDS_DataWriter of an instance for which there isno other DDS_DataWriter.

• The arrival of the notification that an instance has been unregistered by the onlyDDS_DataWriter that is known to be writing the instance.

The read communication statuses are reset to FALSE again in the followingcircumstances:

StatusChangedFlag = TRUE

StatusChangedFlag = FALSE

CurrentStatus != SavedStatusget_<status_name>_statusOR invocation of corres-

event which can causethe activation of a Listener

ponding Listener operation

644C Reference Guide

Appendices

• The status flag of the DDS_DATA_AVAILABLE_STATUS becomes FALSE wheneither the corresponding listener operation (on_data_available) is called, orthe read or take operation (or any of its variants) is called on the associatedDDS_DataReader.

Figure 25: Read Communication Status DDS_DataReader Statecraft

• The status flag of the DDS_DATA_ON_READERS_STATUS becomes FALSE whenany of the following events occurs: - The corresponding listener operation (on_data_on_readers) is called on the

corresponding DDS_Subscriber. - The on_data_available listener operation is called on anyDDS_DataReader belonging to the DDS_Subscriber.

- The read or take operation (or any of its variants) is called on anyDDS_DataReader belonging to the DDS_Subscriber.

StatusChangedFlag = TRUE

StatusChangedFlag = FALSE

Data arrives ORon_data_available ORread/take or any of itsvariants

event which can causethe activation of a Listener

change in InstanceState of a contained instance

645C Reference Guide

Appendices

Figure 26: DDS_Subscriber Statecraft for a Read Communication Status

ListenersThe Listeners provide for an event-based mechanism to asynchronously informthe application of a status change event. Listeners are applicable for both the readcommunication statuses and the plain communication statuses. When one of thesestatus change events occur, the associated Listener is activated, provided somepre-conditions are satisfied. When the Listener is activated, it will call thecorresponding on_<status_name> operation of that Listener. Eachon_<status_name> operation available in the Listener of an DDS_Entity isalso available in the Listener of the factory of the DDS_Entity.For both the read communication statuses and the plain communication statuses aListener is only activated when a Listener is attached to this particularDDS_Entity and enabled for this particular status. Statuses are enabled accordingto the DDS_StatusKindMask parameter that was passed at creation time of theDDS_Entity, or that was passed to the DDS_<DDS_Entity>_set_listeneroperation .When an event occurs for a particular DDS_Entity and for a particular status, butthe applicable Listener is not activated for this status, the status is propagated upto the factory of this DDS_Entity. For this factory, the same propagation rulesapply. When even the DDS_DomainParticipantListener is not attached orenabled for this status, the application will not be notified about this event. Thismeans that a status change on a contained DDS_Entity only invokes the Listenerof its factory if the Listener of the contained DDS_Entity itself does not handlethe trigger event generated by the status change.

StatusChangedFlag = TRUE

StatusChangedFlag = FALSE

Data arrives OR change in InstanceStateon_data_on_readers ORon_data_available ORread/take or any of its

event which can causethe activation of a Listener

of any contained DataReader variants

646C Reference Guide

Appendices

Figure 27: DCPS Listeners

The event propagation is also applicable to the read communication statuses.H o w ev e r, s i n c e t h e e v e n t h e r e i s t h e a r r i va l o f da t a , bo th t h eDDS_DATA_ON_READERS and DDS_DATA_AVAILABLE status are TRUE. The DataDistribution Service will first attempt to handle the DDS_DATA_ON_READERS statusand try to activate the DDS_SubscriberListener. When this Listener is nota c t i v a t e d f o r t h i s s t a t u s , t h e e v e n t w i l l p r o p a g a t e t o t h eDDS_DomainParticipantListener. Only when the DDS_DATA_ON_READERSstatus can not be handled, the Data Distribution Service will attempt to handle theDDS_DATA_AVAILABLE status and try to activate the DDS_DataReaderListener.In case this Listener is not activated for this status, the event will follow thepropagation rules as described above.

Conditions and WaitsetsThe DDS_Conditions in conjunction with DDS_WaitSets provide for await-based mechanism to synchronously inform the application of status changes. ADDS_Condition can be either a DDS_ReadCondition, DDS_QueryCondition,DDS_StatusCondition o r DDS_GuardCondition . To c r e a t e aDDS_Condition one of the following operations can be used:

Listener(from Infrastructure Module)

<<Interface>>

DataWriterListener

on_liveliness_lost()on_offered_deadline_missed()on_offered_incompatible_qos()on_publication_match()

<<Interface>>DataReaderListener

on_data_available()on_liveliness_changed()on_requested_deadline_missed()on_requested_incompatible_qos()on_sample_lost()on_sample_rejected()on_subscription_match()

<<Interface>>

SubscriberListener

on_data_on_readers()

<<Interface>>

PublisherListener<<Interface>>

TopicListener

on_inconsistent_topic()

<<Interface>>

DomainParticipantListener

647C Reference Guide

Appendices

• DDS_ReadCondition created by DDS_DataReader_create_readcondition

• DDS_QueryCondition created by DDS_DataReader_create_querycondition

• DDS_StatusCondition retrieved by DDS_<Entity>_get_statuscondition on an DDS_<Entity>

• DDS_GuardCondition created by the C operationDDS_GuardCondition__alloc

Note that the DDS_QueryCondition is a specialized DDS_ReadCondition. TheDDS_GuardCondition is a different kind of DDS_Condition since it is notc o n t r o l l e d by a s t a t u s b u t d i r e c t l y b y t h e a p p l i c a t i o n ( w h e n aDDS_GuardCondition is initially created, the trigger_value is FALSE). TheDDS_StatusCondition is present by default with each DDS_Entity, therefore, itdoes not have to be created.

Figure 28: DCPS DDS_WaitSets

A DDS_WaitSet may have one or several DDS_Conditions attached to it. Anapplication thread may block execution (blocking may be limited by a timeout) bywaiting on a DDS_WaitSet until the trigger_value of one or more of theDDS_Conditions become TRUE . When a DDS_Condition , whosetrigger_value evaluates to TRUE, is attached to a DDS_WaitSet that is currentlybeing waited on (using the DDS_WaitSet_wait operation), the DDS_WaitSet willunblock immediately.This (wait-based) mechanism is generally used as follows:• The application creates a DDS_WaitSet• The application indicates which relevant information it wants to be notified of, by

creating or retrieving DDS_Condition objects (DDS_StatusCondition,DDS_ReadCondition, DDS_QueryCondition or DDS_GuardCondition) andattach them to a DDS_WaitSet

• It then waits on that DDS_WaitSet (using DDS_WaitSet_wait) until thetrigger_value of one or several DDS_Condition objects (in theDDS_WaitSet) become TRUE

Condition

get_trigger_value()

WaitSet

attach_condition()detach_condition()get_conditions()wait()

** **

648C Reference Guide

Appendices

• When the thread is unblocked, the application uses the result of theDDS_WaitSet_wait (i.e., the list of DDS_Condition objects withtrigger_value==TRUE) to actually get the information: - if the condition is a DDS_StatusCondition and the status changes refer to a

plain communication status, by calling get_status_changes and thenget_<communication_status> on the relevant DDS_Entity

- if the condition is a DDS_StatusCondition and the status changes refer to theread communication status:DDS_DATA_ON_READERS, by calling get_status_changes and thenDDS_Subscriber_get_datareaders on the relevant DDS_Subscriberand then DDS_DataReader_read/DDS_DataReader_take on the returnedDDS_DataReader objectsDDS_DATA_AVAILABLE, by calling get_status_changes and thenDDS_DataReader_read /DDS_DataReader_take on the relevantDDS_DataReader.

- if it is a DDS_ReadCondition or a DDS_QueryCondition, by calling directlyDDS_DataReader_read_w_condition / DDS_DataReader_take_w_condition on the DDS_DataReader with the DDS_Condition as aparameter.

649C Reference Guide

Appendices

Figure 29: DCPS DDS_Conditions

No extra information is passed from the Data Distribution Service to the applicationwhen a DDS_WaitSet_wait returns only the list of triggered DDS_Conditionobjects. Therefore, it is the application responsibility to investigate whichDDS_Condition objects have triggered the DDS_WaitSet.

Blocking BehaviourThe result of a DDS_WaitSet_wait operation depends on the state of theDDS_WaitSet , which in turn depends on whether at least one attachedDDS_Condition has a trigger_value of TRUE. If the DDS_WaitSet_waitoperation is called on DDS_WaitSet with state BLOCKED it will block the callingthread. If DDS_WaitSet_wait is called on a DDS_WaitSet with stateUNBLOCKED it will return immediately. In addition, when the DDS_WaitSettransitions from state BLOCKED to state UNBLOCKED it wakes up the thread (ifany) that had called DDS_WaitSet_wait on it. Note that there can only be onethread waiting on a single DDS_WaitSet.

Condition

get_trigger_value()

QueryCondition

get_query_parameters()get_query_expression()set_query_parameters()

DataReader

ReadCondition

get_datareader()get_instance_state_mask()get_sample_state_mask()get_view_state_mask()

1

*

1

*

GuardCondition

set_trigger_value()

Entity

enable()<<abstract>> get_listener()<<abstract>> get_qos()get_status_changes()get_statuscondition()<<abstract>> set_listener()<<abstract>> set_qos()

StatusCondition

get_enabled_statuses()get_entity()set_enabled_statuses()

11

entity

0..10..1statuscondition

DataWriter

PublisherSubscriber

Topic

DomainParticipant

DomainEntity

<<create>>

<<create>>

650C Reference Guide

Appendices

Figure 30: Blocking Behaviour of a Waitset State Chart

DDS_StatusCondition Trigger StateThe trigger_value of a DDS_StatusCondition is the boolean OR of theStatusChangedFlag of all the communication statuses to which it is sensitive.T h a t i s , trigger_value==FALSE o n l y i f a l l t h e v a lu e s o f t h eStatusChangedFlags are FALSE.The sensitivity of the DDS_StatusCondition to a particular communicationstatus is controlled by the bit-mask of enabled_statuses set on theDDS_Condition b y m e a n s o f t h eDDS_StatusCondition_set_enabled_statuses operation.

DDS_ReadCondition and DDS_QueryCondition Trigger StateSimilar to the DDS_StatusCondition, a DDS_ReadCondition also has atrigger_value that determines whether the attached DDS_WaitSet isBLOCKED or UNBLOCKED. However, unlike the DDS_StatusCondition, thetrigger_value of the DDS_ReadCondition is tied to the presence of at leastone sample managed by the Data Distribution Service with SampleState,ViewState, and InstanceState matching those of the DDS_ReadCondition.Additionally, for the DDS_QueryCondition, the data associated with the sample,must be such that the query_expression evaluates to TRUE.The fact that the trigger_value of a DDS_ReadCondition is dependent on thepresence of samples on the associated DDS_DataReader implies that a singleDDS_DataReader_take operation can potentially change the trigger_value ofseveral DDS_ReadCondition or DDS_QueryCondition objects. For example, ifall samples are taken, any DDS_ReadCondition or DDS_QueryCondition

UNBLOCKED

BLOCKED

[at least one attached condition hastrigger_value == TRUE]

[all attached conditions havetrigger_value == FALSE]

DDS_WaitSet_waitBlock calling thread

DDS_WaitSet_waitDo not block. Return immediately

Wakeup waiting threads

651C Reference Guide

Appendices

o b j ec t s a s soc i a t e d w i th t he DDS_DataReader t ha t h a d t he i rtrigger_value==TRUE before will see the trigger_value change to FALSE.Note that this does not guarantee that DDS_WaitSet objects, that had thoseDDS_Condition objects separately attached to, will not be woken up. Once wehave trigger_value==TRUE on a DDS_Condition it may wake up theDDS_WaitSet i t w a s a t t a c h e d t o , t he c o n d i t i o n t r a n s i t i o n s t otrigger_value==FALSE does not 'un-wake up' the DDS_WaitSet as'un-wakening' is not possible. The consequence is that an application blocked on aDDS_WaitSet may return from the wait with a list of DDS_Condition objectssome of which are no longer “active”. This is unavoidable if multiple threads areconcurrently waiting on separate DDS_WaitSet objects and taking data associatedwi th t he s ame DDS_DataReader DDS_Entity. I n o t he r wor ds , aDDS_WaitSet_wait may return with a list of DDS_Condition objects which allhave a trigger_value==FALSE. This only means that at some point one or moreof the DDS_Condition objects have had a trigger_value==TRUE but no longerdo.

DDS_GuardCondition Trigger StateThe trigger_value of a DDS_GuardCondition is completely controlled by theapplication via the operation DDS_GuardCondition_set_trigger_value. ThisDDS_Condition can be used to implement an application-defined wake-up of theblocked thread.

652C Reference Guide

Appendix

G DDS_Topic DefinitionsThe Data Distribution Service distributes its data in structured data types, calledtopics. The first step when using the Data Distribution Service consists of definingthese topics. Since the Data Distribution Service supports using severalprogramming languages, OMG IDL is used for this purpose. This appendixdescribes how to define the topics.

DDS_Topic Definition ExampleAll data distributed using the Data Distribution Service has to be defined as a topic.A topic is a structured data type, like a C-struct with several members. Wheneverthe application needs to read or write data, it will be reading or writing topics. Thedefinition of each topic it will be using has to be written in (a subset of) OMG IDL.For example:

module SPACE {struct Foo {

long userID; // owner of messagelong long index; // message index per ownerstring content; // message body

};#pragma keylist Foo};

This is the definition of a topic called Foo, used for sending and receiving messages(as an example). Even though the topic is defined using IDL, the Data DistributionService will be using an equivalent C-struct which is accessed by the applicationusing the type specific operations. Generation of the typed classes is achieved byinvoking the Data Distribution Service IDL pre-processor: idlpp -l c -S<idl_filename>.idl, a tool which translates the IDL topic definition into anequivalent C definition. The -l C option indicates that C-code has to be generated,the -S option indicates that this C code should be StandAlone C code, i.e. it must nothave any dependency on external ORB libraries. In this example, the pre-processorwill generate the classes SPACE_FooTypeSupport, SPACE_FooDataWriter andSPACE_FooDataReader which contain the type specific operations.The prefix SPACE_ is generated from the IDL-module-name. The types of the fieldsare prescribed by the IDL-to-C mapping. After the Data Distribution ServiceIDL-pre-processor is run, the application will use the generated code.

653C Reference Guide

Appendices

Complex TopicsThe Foo topic is relatively simple, but the Data Distribution Service is capable ofdistributing more complex topics as well. In fact, any definition following theOpenSplice IDL subset is allowed. For a reference of this subset, see theBNF-notation in Appendix , Data Distribution Service IDL Subset in BNF Notation.It is important to know that the pre-processor accepts all IDL constructs but only thesubset is being processed.Apart from the trivial data types, the Data Distribution Service is capable ofhandling fixed-length arrays, bounded and unbounded sequences, union types andenumerations. Types can be nested, e.g. a struct can contain a struct field or an arrayof structs, or a sequence of strings or an array of sequences containing structs. Formore information regarding the IDL to C mapping.

IDL Pre-processorThis section contains the specification of the subset of OMG IDL that can be used todefine the topics.

IDL to Host Language MappingThe Data Distribution Service IDL pre-processor translates the IDL-definition of thetopics into language specific code. This translation is executed according to theOMG IDL mappings. Since the Data Distribution Service uses data-structures only,not all IDL-features are implemented by the pre-processor. Usually, the IDLdefinition consists of a module defining several structs and typedefs.

Data Distribution Service IDL KeywordsThe identifiers listed in this appendix are reserved for use as keywords in IDL andmay not be used otherwise, unless escaped with a leading underscore.

abstract exception inout provides truncatableany emits interface public typedefattribute enum local publishes typeidboolean eventtype long raises typeprefixcase factory module readonly unsignedchar FALSE multiple setraises unioncomponent finder native sequence usesconst fixed Object short ValueBaseconsumes float octet string valuetypecontext getraises oneway struct void

654C Reference Guide

Appendices

Keywords must be written exactly as shown in the above list. Identifiers that collidewith keywords are illegal. For example, boolean is a valid keyword; Boolean andBOOLEAN are illegal identifiers.

Data Distribution Service IDL Pragma KeylistTo define a topic, the content must either be a struct or a union. The pre-processorwill only generate the type specific classes when topic definition is accompanied bya <pragmakeylist>. When the <pragmakeylist> has no <field_id>,the topic is available but no key is set. To define the keylist the definition, written inBNF-notation, is as follows:

<pragmakeylist>::= “#pragma keylist” <type_id> <field_id>*

<type_id>::= <struct_type_identifier> | <union_type_identifier>

<field_id>::= <member_declarator> | <element_spec_declarator>

In case of a struct, <type_id> is a <struct_type_identifier>. In case of a union,<type_id> is a <union_type_identifier>. The <struct_type_identifier> is theidentifier used in the struct declaration. The <union_type_identifier> is theidentifier used in the union declaration. The <field_id> is the identifier of a field inthe struct or union identified by <type_id>. In case of a struct, <field_id> is a<member_declarator> which is one of the declarators used in the struct member. Incase of a union, <field_id> is a <element_spec_declarator> which is one of thedeclarators used in the element specification in a case of the union.For example, for the Foo example in Appendix , DDS_Topic Definition Example thenext pragma must be used to have the pre-processor generate the typed classes(SPACE_FooTypeSupport, SPACE_FooDataWriter and SPACE_FooDataReader).

#pragma keylist Foo userID index

Note that in this example the userID and the index are used as a key.

Data Distribution Service IDL Subset in BNF NotationOnly a subset is used by the pre-processor. A description of the Data DistributionService IDL subset, written in BNF-notation, is as follows:

<definition>::= <type_dcl> “;” | <const_dcl> “;”

custom home out supports wchardefault import primarykey switch wstringdouble in private TRUE

655C Reference Guide

Appendices

| <module> “;”<module>::= “module” <identifier> “{“ <definition>+ “}”<scoped_name>::= <identifier>

| “::” <identifier> | <scoped_name> “::” <identifier>

<const_dcl>::= “const” <const_type> <identifier> “=” <const_exp>

<const_type>::= <integer_type> | <char_type> | <boolean_type> | <floating_pt_type> | <string_type> | <scoped_name> | <octet_type>

<const_exp>::= <or_expr><or_expr>::= <xor_expr>

| <or_expr> “|” <xor_expr><xor_expr>::= <and_expr>

| <xor_expr> “^” <and_expr><and_expr>::= <shift_expr>

| <and_expr> “&” <shift_expr><shift_expr>::= <add_expr>

| <shift_expr> “>>” <add_expr> | <shift_expr> “<<” <add_expr>

<add_expr>::= <mult_expr> | <add_expr> “+” <mult_expr> | <add_expr> “-” <mult_expr>

<mult_expr>::= <unary_expr> | <mult_expr> “*” <unary_expr> | <mult_expr> “/” <unary_expr> | <mult_expr> “%” <unary_expr>

<unary_expr>::= <unary_operator> <primary_expr> | <primary_expr>

<unary_operator>::= “-” | “+” | “~”

<primary_expr>::= <scoped_name> | <literal> | “(” <const_exp> “)”

<literal>::= <integer_literal> | <string_literal> | <character_literal> | <floating_pt_literal> | <boolean_literal>

<boolean_literal>::= “TRUE” | “FALSE”

<positive_int_const>::= <const_exp><type_dcl>::= “typedef” <type_declarator>

| <struct_type> | <union_type>

656C Reference Guide

Appendices

| <enum_type><type_declarator>::= <type_spec> <declarators><type_spec>::= <simple_type_spec>

| <constr_type_spec><simple_type_spec>::= <base_type_spec>

| <template_type_spec> | <scoped_name>

<base_type_spec>::= <floating_pt_type> | <integer_type> | <char_type> | <boolean_type> | <octet_type>

<template_type_spec>::= <sequence_type> | <string_type>

<constr_type_spec>::= <struct_type> | <union_type> | <enum_type>

<declarators>::= <declarator> { “,” <declarator> }*<declarator>::= <simple_declarator>

| <complex_declarator><simple_declarator>::= <identifier><complex_declarator>::= <array_declarator><floating_pt_type>::= “float”

| “double”<integer_type>::= <signed_int>

| <unsigned_int><signed_int>::= <signed_short_int>

| <signed_long_int> | <signed_longlong_int>

<signed_short_int>::= “short”<signed_long_int>::= “long”<signed_longlong_int>::= “long” “long”<unsigned_int>::= <unsigned_short_int>

| <unsigned_long_int> | <unsigned_longlong_int>

<unsigned_short_int>::= “unsigned” “short”<unsigned_long_int>::= “unsigned” “long”<unsigned_longlong_int>::= “unsigned” “long” “long”<char_type>::= “char”<boolean_type>::= “boolean”<octet_type>::= “octet”<struct_type>::= “struct” <identifier> “{” <member_list> “}”<member_list>::= <member>+<member>::= <type_spec> <declarators> “;”<union_type>::= “union” <identifier> “switch”

“(” <switch_type_spec> “)” “{” <switch_body> “}”

<switch_type_spec>::= <integer_type> | <char_type> | <boolean_type>

657C Reference Guide

Appendices

| <enum_type> | <scoped_name>

<switch_body>::= <case>+<case>::= <case_label>+ <element_spec> “;”<case_label>::= “case” <const_exp> “:”

| “default” “:”<element_spec>::= <type_spec> <declarator><enum_type>::= “enum” <identifier>

“{” <enumerator> { “,” <enumerator> }* “}”<enumerator>::= <identifier><sequence_type>::= “sequence” “<” <simple_type_spec> “,”

<positive_int_const> “>” | “sequence” “<” <simple_type_spec> “>”

<string_type>::= “string” “<” <positive_int_const> “>” | “string”

<array_declarator>::= <identifier> <fixed_array_size>+<fixed_array_size>::= “[” <positive_int_const> “]”

658C Reference Guide

Appendix

H DCPS Queries and FiltersA subset of SQL syntax is used in several parts of OpenSplice:• the filter_expression in the DDS_ContentFilteredTopic• the topic_expression in the DDS_MultiTopic• the query_expression in the DDS_QueryReadCondition.Those expressions may use a subset of SQL, extended with the possibility to useprogram variables in the SQL expression. The allowed SQL expressions are definedwith the BNF-grammar below. The following notational conventions are made:• the NonTerminals are typeset in italics• the ‘Terminals’ are quoted and typeset in a fixed width font• the TOKENS are typeset in small caps• the notation (element // ‘,’) represents a non-empty comma-separated list of

elements.

SQL Grammar in BNFExpression::= FilterExpression

| TopicExpression | QueryExpression

FilterExpression::= ConditionTopicExpression::= SelectFrom {Where } ‘;’QueryExpression::= {Condition}{‘ORDER BY’ (FIELDNAME // ‘,’) } SelectFrom::= ‘SELECT’ Aggregation ‘FROM’ SelectionAggregation::= ‘*’

| (SubjectFieldSpec // ‘,’)SubjectFieldSpec::= FIELDNAME

| FIELDNAME ‘AS’ FIELDNAME | FIELDNAME FIELDNAME

Selection::= TOPICNAME | TOPICTNAME NaturalJoin JoinItem

JoinItem::= TOPICNAME | TOPICNAME NaturalJoin JoinItem | ‘(’ TOPICNAME NaturalJoin JoinItem ‘)’

NaturalJoin::= ‘INNER NATURAL JOIN’ | ‘NATURAL JOIN’ | ‘NATURAL INNER JOIN’

Where::= ‘WHERE’ ConditionCondition::= Predicate

| Condition ‘AND’ Condition

659C Reference Guide

Appendices

| Condition ‘OR’ Condition | ‘NOT’ Condition | ‘(’ Condition ‘)’

Predicate::= ComparisonPredicate | BetweenPredicate

ComparisonPredicate::= FIELDNAME RelOp Parameter | Parameter RelOp FIELDNAME

BetweenPredicate::= FIELDNAME ‘BETWEEN’ Range | FIELDNAME ‘NOT BETWEEN’ Range

RelOp::= ‘=’ | ‘>’ | ‘>=’ | ‘<’ | ‘<=’ | ‘<>’ | likeRange::= Parameter ‘AND’ ParameterParameter::= INTEGERVALUE

| FLOATVALUE | STRING | ENUMERATEDVALUE | PARAMETER

Note: INNER NATURAL JOIN, NATURAL JOIN, and NATURAL INNER JOIN areall aliases, in the sense that they have the same semantics. The aliases are allsupported because they all are part of the SQL standard.

SQL Token ExpressionThe syntax and meaning of the tokens used in the SQL grammar is described asfollows:FIELDNAME - A fieldname is a reference to a field in the data-structure. The dot‘.’ is used to navigate through nested structures. The number of dots that may beused in a fieldname is unlimited. The field-name can refer to fields at any depth inthe data structure. The names of the field are those specified in the IDL definition ofthe corresponding structure, which may or may not match the field names thatappear on the C mapping of the structureTOPICNAME - A topic name is an identifier for a topic, and is defined as any seriesof characters ‘a’, ..., ‘z’, ‘A’, ..., ‘Z’, ‘0’, ..., ‘9’, ‘_’ but may not startwith a digitINTEGERVALUE - Any series of digits, optionally preceded by a plus or minus sign,representing a decimal integer value within the range of the system. A hexadecimalnumber is preceded by 0x and must be a valid hexadecimal expressionFLOATVALUE - Any series of digits, optionally preceded by a plus or minus sign andoptionally including a floating point (‘.’). A power-of-ten expression may bepost-fixed, which has the syntax en, where n is a number, optionally preceded by aplus or minus sign

660C Reference Guide

Appendices

STRING - Any series of characters encapsulated in single quotes, except a new-linecharacter or a right quote. A string starts with a left or right quote, but ends with aright quoteENUMERATEDVALUE - An enumerated value is a reference to a value declared withinan enumeration. The name of the value must correspond to the names specified inthe IDL definition of the enumeration, and must be encapsulated in single quotes.An enum value starts with a left or right quote, but ends with a right quote.PARAMETER - A parameter is of the form %n, where n represents a natural number(zero included) smaller than 100. It refers to the n + 1th argument in the givencontext.Note: when RelOp is ‘like’, Unix filename wildcards must be used for stringsinstead of the normal SQL wildcards. This means any one character is ‘?’, any zeroor more characters is ‘*’

SQL ExamplesAssuming Topic “Location” has as an associated type a structure with fields“flight_name, x, y, z”, and Topic “FlightPlan” has as fields “flight_id, source,destination”. The following are examples of using these expressions.Example of a topic_expression:

“SELECT flight_name, x, y, z AS height FROM ‘Location’ NATURAL JOIN‘FlightPlan’ WHERE height < 1000 AND x <23”.

Example of a query_expression or a filter_expression:“height < 1000 AND x <23”.

661C Reference Guide

Appendices

662C Reference Guide

Appendix

I Built-in TopicsAs part of its operation, the middleware must discover and possibly keep track ofthe presence of remote entities such as a new participant in the domain. Thisinformation may also be important to the application, which may want to react tothis discovery, or else access it on demand.To make this information accessible to the application, the DCPS specificationintroduces a set of built-in topics and corresponding DataReader objects that canthen be used by the application. The information is then accessed as normalapplication data. This approach avoids introducing a new API to access thisinformation and allows the application to become aware of any changes in thosevalues by means of any of the mechanisms presented in Appendix F, Listeners,Conditions and Waitsets.The built-in data-readers all belong to a built-in Subscriber. This subscriber can beretrieved by using the method get_builtin_subscriber provided by theD o m a i n P a r t i c i p a n t ( f o r d e t a i l s , s e e S e c t i o n 3 . 2 . 1 . 1 6 ,DDS_DomainParticipant_get_builtin_subscriber, on page 190). The built-inDataReader objects can be retrieved by using the operation lookup_datareader,with the Subscriber and the topic name as parameter (for details, see Section3.5.1.15, DDS_Subscriber_lookup_datareader, on page 412).The QoS of the built-in Subscriber and DataReader objects is given by the followingtable:

Table 27: Built-in Subscriber and DataReader QoSUSER_DATA <empty>

TOPIC_DATA <empty>

GROUP_DATA <empty>

DURABILITY TRANSIENT

DURABILITY_SERVICE service_cleanup_delay = 0history_kind = KEEP_LASThistory_depth = 1max_samples = LENGTH_UNLIMITEDmax_instances = LENGTH_UNLIMITEDmax_samples_per_instance = LENGTH_UNLIMITED

663C Reference Guide

Appendices

Built-in entities have default listener settings as well. The built-in Subscriber and allof its built-in Topics have nil listeners with all statuses appearing in their listenermasks. The built-in DataReaders have nil listeners with no statuses in their masks.The information that is accessible about the remote entities by means of the built-intopics includes all the QoS policies that apply to the corresponding remote Entity.The QoS policies appear as normal 'data' fields inside the data read by means ofthe built-in Topic. Additional information is provided to identify the Entity andfacilitate the application logic.

PRESENTATION access_scope = TOPICcoherent_access = FALSEordered_access = FALSE

DEADLINE Period = infinite

LATENCY_BUDGET duration = 0

OWNERSHIP SHARED

LIVELINESS kind = AUTOMATIClease_duration = 0

TIME_BASED_FILTER minimum_separation = 0

PARTITION __BUILT-IN PARTITION__

RELIABILITY kind = RELIABLEmax_blocking_time = 100 millisecondssynchronous = FALSE

DESTINATION_ORDER BY_RECEPTION_TIMESTAMP

HISTORY kind = KEEP_LASTdepth = 1

RESOURCE_LIMITS max_samples = LENGTH_UNLIMITEDmax_instances = LENGTH_UNLIMITEDmax_samples_per_instance = LENGTH_UNLIMITED

READER_DATA_LIFECYCLE autopurge_nowriter_samples_delay = INFINITEautopurge_disposed_samples_delay = INFINITEinvalid_sample_visibility = MINIMUM_INVALID_SAMPLES

ENTITY_FACTORY autoenable_created_entities = TRUE

SHARE enable = FALSEname = NULL

READER_DATA_LIFESPAN used = FALSEduration = INFINITE

USER_KEY enable = FALSEexpression = NULL

Table 27: Built-in Subscriber and DataReader QoS (continued)

664C Reference Guide

Appendices

The tables below list the built-in topics, their names, and the additional information(beyond the QoS policies that apply to the remote entity) that appears in the dataassociated with the built-in topic.

ParticipantBuiltinTopicDataThe DCPSParticipant topic communicates the existence of DomainParticipantsby means of the ParticipantBuiltinTopicData da ta type . EachParticipantBuiltinTopicData sample in a Domain represents aD o m a i n P a r t i c i p a n t t h a t p a r t i c i p a t e s i n t h a t D o m a i n : a n e wParticipantBuiltinTopicData instance is created when a newly addedDomainParticipant is enabled, and it is disposed when that DomainParticipant isdeleted. An updated ParticipantBuiltinTopicData sample is written eachtime the DomainParticipant modifies its UserDataQosPolicy.

TopicBuiltinTopicDataThe DCPSTopic topic communicates the existence of topics by means of theTopicBuiltinTopicData datatype. Each TopicBuiltinTopicData sample ina Domain represents a Topic in that Domain: a new TopicBuiltinTopicDatainstance is created when a newly added Topic is enabled. However, the instance isnot disposed when a Topic is deleted by its participant because a topic lifecycle istied to the lifecycle of a Domain, not to the lifecycle of an individual participant.(See also Section 3.2.1.13, DDS_DomainParticipant_delete_topic, on page 186,which explains that a DomainParticipant can only delete its local proxy to the realTopic). An updated TopicBuiltinTopicData sample is written each time aTopic modifies one or more of its QosPolicy values.Information published in the DCPSTopicTopic is critical to the data distributionservice, therefore it cannot be disabled by means of the Domain/BuiltinTopicselement in the configuration file.

Table 28: ParticipantBuiltinTopicData Members

Name Type Descriptionkey BuiltinTopicKey_t Globally unique identifier of the

participantuser_data UserDataQosPolicy User-defined data attached to the

participant via a QosPolicy

665C Reference Guide

Appendices

PublicationBuiltinTopicDataThe DCPSPublication topic communicates the existence of datawriters by meanso f t he PublicationBuiltinTopicData d a t a t y p e . E a c hPublicationBuiltinTopicData sample in a Domain represents a datawriter inthat Domain: a new PublicationBuiltinTopicData instance is created when anewly added DataWriter is enabled, and it is disposed when that DataWriter isdeleted. An updated PublicationBuiltinTopicData sample is written eachtime the DataWriter (or the Publisher to which it belongs) modifies a QosPolicy thatapplies to the entities connected to it. Also will it be updated when the writer loosesor regains its liveliness.The PublicationBuiltinTopicData Topic is also used to return data throughthe get_matched_publication_data operation on the DataReader as describedin Section 3.5.2.13, DDS_DataReader_get_matched_publication_data, on page437.

Table 29: TopicBuiltinTopicData MembersName Type Description

key BuiltinTopicKey_t Global unique identifier of the Topicname String Name of the Topictype_name String Type name of the Topic (i.e. the fully

scoped IDL name)durability DurabilityQosPolicy QosPolicy attached to the Topicdurability_service DurabilityServiceQosPolicy QosPolicy attached to the Topicdeadline DeadlineQosPolicy QosPolicy attached to the Topiclatency_budget LatencyBudgetQosPolicy QosPolicy attached to the Topicliveliness LivelinessQosPolicy QosPolicy attached to the Topicreliability ReliabilityQosPolicy QosPolicy attached to the Topictransport_priority TransportPriorityQosPolicy QosPolicy attached to the Topiclifespan LifespanQosPolicy QosPolicy attached to the Topicdestination_order DestinationOrderQosPolicy QosPolicy attached to the Topichistory HistoryQosPolicy QosPolicy attached to the Topicresource_limits ResourceLimitsQosPolicy QosPolicy attached to the Topicownership OwnershipQosPolicy QosPolicy attached to the Topictopic_data TopicDataQosPolicy QosPolicy attached to the Topic

666C Reference Guide

Appendices

SubscriptionBuiltinTopicDataThe DCPSSubscription topic communicates the existence of datareaders bymeans o f t he SubscriptionBuiltinTopicData d a t a type . EachSubscriptionBuiltinTopicData sample in a Domain represents a datareaderin that Domain: a new SubscriptionBuiltinTopicData instance is createdwhen a newly added DataReader is enabled, and it is disposed when that

Table 30: PublicationBuiltinTopicData MembersName Type Description

key BuiltinTopicKey_t Global unique identifier of the DataWriterparticipant_key BuiltinTopicKey_t Global unique identifier of the Participant to

which the DataWriter belongstopic_name String Name of the Topic used by the DataWritertype_name String Type name of the Topic used by the

DataWriterdurability DurabilityQosPolicy QosPolicy attached to the DataWriterdeadline DeadlineQosPolicy QosPolicy attached to the DataWriterlatency_budget LatencyBudgetQosPolicy QosPolicy attached to the DataWriterliveliness LivelinessQosPolicy QosPolicy attached to the DataWriterreliability ReliabilityQosPolicy QosPolicy attached to the DataWriterlifespan LifespanQosPolicy QosPolicy attached to the DataWriterdestination_order DestinationOrderQosPolicy QosPolicy attached to the DataWriteruser_data UserDataQosPolicy QosPolicy attached to the DataWriterownership OwnershipQosPolicy QosPolicy attached to the DataWriterownership_strength OwnershipStrengthQosPolicy QosPolicy attached to the DataWriterpresentation PresentationQosPolicy QosPolicy attached to the Publisher to which

the DataWriter belongspartition PartitionQosPolicy QosPolicy attached to the Publisher to which the

DataWriter belongs

topic_data TopicDataQosPolicy QosPolicy attached to the Topic used by theDataWriter

group_data GroupDataQosPolicy QosPolicy attached to the Publisher to which theDataWriter belongs

667C Reference Guide

Appendices

DataReader is deleted. An updated SubscriptionBuiltinTopicData sample iswritten each time the DataReader (or the Subscriber to which it belongs) modifies aQosPolicy that applies to the entities connected to it.The SubscriptionBuiltinTopicData Topic is also used to return data throughthe get_matched_subscription_data operation on the DataWriter asdescribed in Section 3.4.2.9, DDS_DataWriter_get_matched_subscription_data, onpage 326.

Table 31: SubscriptionBuiltinTopicData MembersName Type Description

key BuiltinTopicKey_t Global unique identifier of the DataReaderparticipant_key BuiltinTopicKey_t Global unique identifier of the Participant

to which the DataReader belongstopic_name String Name of the Topic used by the DataReadertype_name String Type name of the Topic used by the

DataReaderdurability DurabilityQosPolicy QosPolicy attached to the DataReaderdeadline DeadlineQosPolicy QosPolicy attached to the DataReaderlatency_budget LatencyBudgetQosPolicy QosPolicy attached to the DataReaderliveliness LivelinessQosPolicy QosPolicy attached to the DataReaderreliability ReliabilityQosPolicy QosPolicy attached to the DataReaderownership LifespanQosPolicy QosPolicy attached to the DataReaderdestination_order DestinationOrderQosPolicy QosPolicy attached to the DataReaderuser_data UserDataQosPolicy QosPolicy attached to the DataReadertime_based_filter TimeBasedFilterQosPolicy QosPolicy attached to the DataReaderpresentation PresentationQosPolicy QosPolicy attached to the Subscriber to

which the DataReader belongspartition PartitionQosPolicy QosPolicy attached to the Subscriber to

which the DataReader belongstopic_data TopicDataQosPolicy QosPolicy attached to the Topic used by the

DataReadergroup_data GroupDataQosPolicy QosPolicy attached to the Subscriber to

which the DataReader belongs

668C Reference Guide

Appendices

Other builtin topicsThere are a number of other built-in topics that have not been mentioned. Thesetopics (e.g. DCPSDelivery, DCPSHeartbeat and potentially some others) areproprietary and for internal use only. Users are discouraged from doing anythingwith these topics, so as not to interfere with internal mechanisms that rely on them.The structure of these topics may change without notification.

669C Reference Guide

Appendices

670C Reference Guide

BIBLIOGRAPHY

Bibl iography[1] OMG Data Distribution Service Revised Final Adopted Specification ptc/04-03-07, Object

Management Group[2] OMG C Language Mapping Specification formal/99-07-35, Object Management Group (OMG)[3] OMG The Common Object Request Broker: Architecture and Specification, Version 3.0,

formal/02-06-01, Object Management Group

673C Reference Guide

Bibliography

674C Reference Guide

GLOSSARY

GlossaryAcronymsAcronym MeaningCORBA Common Object Request Broker ArchitectureDCPS Data Centric Publish/SubscribeDDS Data Distribution ServiceIDL Interface Definition Language

OMG Object Management GroupORB Object Request BrokerQoS Quality of ServiceSPLICE Subscription Paradigm for the Logical Interconnection of Concurrent Engines

677C Reference Guide

Glossary

678C Reference Guide

INDEX

Index

AAbout the C Reference Guide. . . . . . . . . . . . . xxiii Affected Entities. . . . . . . . . . . . . . . . . . . . . . . . 577

BBasic Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 577Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . 673

Blocking Behaviour . . . . . . . . . . . . . . . . . . . . . 650Blocking Behaviour of a Waitset State Chart . 651

CC Reference Guide Document Structure . . . . . . . 3Changeable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Class DDS_Condition . . . . . . . . . . . . . . . . . . . 143Class DDS_ContentFilteredTopic . . . . . . . . . . 268Class DDS_DataReader (abstract) . . . . . . . . . . 421Class DDS_DataSample. . . . . . . . . . . . . . . . . . 505Class DDS_DataWriter (abstract) . . . . . . . . . . 317Class DDS_DomainEntity (abstract) . . . . . . . . .59Class DDS_DomainParticipant . . . . . . . . . . . . 161Class DDS_DomainParticipantFactory . . . . . . 220Class DDS_Entity (abstract). . . . . . . . . . . . . . . . 52Class DDS_GuardCondition . . . . . . . . . . . . . . 145Class DDS_MultiTopic . . . . . . . . . . . . . . . . . . 273Class DDS_Publisher . . . . . . . . . . . . . . . . . . . . 290Class DDS_QueryCondition . . . . . . . . . . . . . . 529Class DDS_ReadCondition . . . . . . . . . . . . . . .525

Class DDS_StatusCondition . . . . . . . . . . . . . . 148Class DDS_Subscriber . . . . . . . . . . . . . . . . . . . 392Class DDS_Topic. . . . . . . . . . . . . . . . . . . . . . . 258Class DDS_TopicDescription (abstract) . . . . . 255Class DDS_TypeSupport (abstract) . . . . . . . . . 283Class DDS_WaitSet . . . . . . . . . . . . . . . . . . . . . 136Class Model of the DCPS Topic-Definition

Module . . . . . . . . . . . . . . . . . . . . . . . . . . . 254Class SPACE_FooDataReader. . . . . . . . . . . . . 465Class SPACE_FooDataWriter . . . . . . . . . . . . . 345Class SPACE_FooTypeSupport. . . . . . . . . . . . 285Communication Status . . . . . . . . . . . . . . . . . . 641Communication Status Event . . . . . . . . . . . . . . 643Complex Topics . . . . . . . . . . . . . . . . . . . . . . . . 654Conditions and waitsets . . . . . . . . . . . . . . . . . . 647Contacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv

DData Distribution Service Defined Type . . . . . . 11Data Distribution Service IDL Keywords . . . . 654Data Distribution Service IDL Pragma Keylist 655Data Distribution Service IDL Subset in BNF

Notation. . . . . . . . . . . . . . . . . . . . . . . . . . . 655Data Type “Foo” Typed Classes Pre-processor

Generation . . . . . . . . . . . . . . . . . . . . . . . . . . 46DCPS DDS_Conditions . . . . . . . . . . . . . . 144, 650DCPS DDS_Status Values . . . . . . . . . . . . . . . . 120DCPS DDS_WaitSets. . . . . . . . . . . . . . . . 136, 648DCPS Domain Module’s Class Model. . . . 44, 161DCPS Infrastructure Module’s Class Model 42, 52

DCPS Inheritance. . . . . . . . . . . . . . . . . . . . . . . 639DCPS Listeners . . . . . . . . . . . . . . . . . . . . 117, 647DCPS Module Composition. . . . . . . . . . . . . . . . 41DCPS Publication Module’s Class Model . . . . . 47DCPS Subscription Module’s Class Model . . . . 48DCPS Topic-Definition Module’s Class Model 45DDS___alloc . . . . . . . . . . . . . . . . . . . . . . . . . . . 19DDS___alloc . . . . . . . . . . . . . . . . . . . . . . . . . . . 18DDS___alloc . . . . . . . . . . . . . . . . . . . . . . . . . . . 20DDS__allocbuf. . . . . . . . . . . . . . . . . . . . . . . . . . 18DDS_Condition_get_trigger_value . . . . . . . . . 144DDS_ContentFilteredTopic_get_expression_para

681C Reference Guide

Index

meters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270DDS_ContentFilteredTopic_get_filter_expression

271DDS_ContentFilteredTopic_get_name (inherited)

271DDS_ContentFilteredTopic_get_participant

(inherited). . . . . . . . . . . . . . . . . . . . . . . . . 272DDS_ContentFilteredTopic_get_related_topic 272DDS_ContentFilteredTopic_get_type_name

(inherited). . . . . . . . . . . . . . . . . . . . . . . . . 273DDS_ContentFilteredTopic_set_expression_para

meters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273DDS_DataReader . . . . . . . . . . . . . . . . . . . . . . 645DDS_DataReader_create_querycondition . . . 427DDS_DataReader_create_readcondition . . . . 428DDS_DataReader_delete_contained_entities . 430DDS_DataReader_delete_readcondition . . . . 432DDS_DataReader_enable (inherited) . . . . . . . 434DDS_DataReader_get_key_value (abstract). . 435DDS_DataReader_get_listener . . . . . . . . . . . . 436DDS_DataReader_get_liveliness_changed_status

436DDS_DataReader_get_matched_publication_data

437DDS_DataReader_get_matched_publications 439DDS_DataReader_get_qos . . . . . . . . . . . . . . . 441DDS_DataReader_get_requested_deadline_misse

d_status. . . . . . . . . . . . . . . . . . . . . . . . . . . 442DDS_DataReader_get_requested_incompatible_q

os_status . . . . . . . . . . . . . . . . . . . . . . . . . . 443DDS_DataReader_get_sample_lost_status . . . 444DDS_DataReader_get_sample_rejected_status446DDS_DataReader_get_status_changes (inherited)

447DDS_DataReader_get_statuscondition (inherited)

447DDS_DataReader_get_subscriber. . . . . . . . . . 447DDS_DataReader_get_subscription_match_status

448DDS_DataReader_get_topicdescription . . . . . 449DDS_DataReader_lookup_instance (abstract) 336,

450DDS_DATAREADER_QOS_DEFAULT . . . 581DDS_DataReader_read (abstract) . . . . . . . . . . 450DDS_DataReader_read_instance (abstract) . . 451

DDS_DataReader_read_next_instance (abstract). 451

DDS_DataReader_read_next_instance_w_condition (abstract) . . . . . . . . . . . . . . . . . . . . . . . 452

DDS_DataReader_read_next_sample (abstract). . 452

DDS_DataReader_read_w_condition (abstract). . 452

DDS_DataReader_return_loan (abstract) . . . . 453DDS_DataReader_set_listener . . . . . . . . . . . . 454DDS_DataReader_set_qos . . . . . . . . . . . . . . . 457DDS_DataReader_take (abstract) . . . . . . . . . . 458DDS_DataReader_take_instance (abstract) . . 459DDS_DataReader_take_next_instance (abstract) .

459DDS_DataReader_take_next_instance_w_conditi

on (abstract) . . . . . . . . . . . . . . . . . . . . . . . 460DDS_DataReader_take_next_sample (abstract). .

460DDS_DataReader_take_w_condition (abstract) . .

461DDS_DataReader_wait_for_historical_data. . 461DDS_DataReaderListener. . . . . . . . . . . . . . . . . 38DDS_DataReaderListener interface . . . . . . . . 516DDS_DataReaderListener__alloc. . . . . . . . . . 517DDS_DataReaderListener_on_data_available

(abstract) . . . . . . . . . . . . . . . . . . . . . . . . . 518DDS_DataReaderListener_on_liveliness_changed

(abstract) . . . . . . . . . . . . . . . . . . . . . . . . . 519DDS_DataReaderListener_on_requested_deadline

_missed (abstract) . . . . . . . . . . . . . . . . . . 520DDS_DataReaderListener_on_requested_incomp

atible_qos (abstract) . . . . . . . . . . . . . . . . . 521DDS_DataReaderListener_on_sample_lost

(abstract) . . . . . . . . . . . . . . . . . . . . . . . . . 522DDS_DataReaderListener_on_sample_rejected

(abstract) . . . . . . . . . . . . . . . . . . . . . . . . . 522DDS_DataReaderListener_on_subscription_matc

h (abstract) . . . . . . . . . . . . . . . . . . . . . . . . 523DDS_DataReaderQos . . . . . . . . . . . . . . . . . . . 579DDS_DataWriter_assert_liveliness . . . . . . . . 321DDS_DataWriter_dispose (abstract). . . . . . . . 323DDS_DataWriter_dispose_w_timestamp

(abstract) . . . . . . . . . . . . . . . . . . . . . 323, 345DDS_DataWriter_enable (inherited) . . . . . . . 323

682C Reference Guide

Index

DDS_DataWriter_get_key_value (abstract). . . 324DDS_DataWriter_get_listener . . . . . . . . . . . . . 324DDS_DataWriter_get_liveliness_lost_status . . 324DDS_DataWriter_get_matched_subscription_data

326DDS_DataWriter_get_matched_subscriptions.327DDS_DataWriter_get_offered_deadline_missed_s

tatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329DDS_DataWriter_get_offered_incompatible_qos_

status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330DDS_DataWriter_get_publication_match_status .

332DDS_DataWriter_get_publisher . . . . . . . . . . . 333DDS_DataWriter_get_qos . . . . . . . . . . . . . . . . 334DDS_DataWriter_get_status_changes (inherited) .

335DDS_DataWriter_get_statuscondition (inherited) .

335DDS_DataWriter_get_topic . . . . . . . . . . . . . . . 335DDS_DATAWRITER_QOS_DEFAULT . . . . 584DDS_DataWriter_register_instance (abstract) .336DDS_DataWriter_register_instance_w_timestamp

(abstract) . . . . . . . . . . . . . . . . . . . . . . . . . . 337DDS_DataWriter_set_listener . . . . . . . . . . . . . 337DDS_DataWriter_set_qos . . . . . . . . . . . . . . . . 339DDS_DataWriter_unregister_instance (abstract) . .

341DDS_DataWriter_unregister_instance_w_timesta

mp (abstract) . . . . . . . . . . . . . . . . . . . . . . . 341DDS_DataWriter_write (abstract) . . . . . . . . . . 344DDS_DataWriter_write_w_timestamp (abstract) .

344DDS_DataWriterListener . . . . . . . . . . . . . . . . . . 35DDS_DataWriterListener interface . . . . . . . . . 385DDS_DataWriterListener__alloc . . . . . . . . . . . 386DDS_DataWriterListener_on_liveliness_lost

(abstract) . . . . . . . . . . . . . . . . . . . . . . . . . . 387DDS_DataWriterListener_on_offered_deadline_

missed (abstract) . . . . . . . . . . . . . . . . . . . . 388DDS_DataWriterListener_on_offered_incompatib

le_qos (abstract) . . . . . . . . . . . . . . . . . . . . 389DDS_DataWriterListener_on_publication_match

(abstract) . . . . . . . . . . . . . . . . . . . . . . . . . . 390DDS_DataWriterQos . . . . . . . . . . . . . . . . . . . . 582dds_dcps.idl . . . . . . . . . . . . . . . . . . . . . . . . . . . 599

DDS_DeadlineQosPolicy. . . . . . . . . . . . 69, 70, 84DDS_DestinationOrderQosPolicy . . . . . . . . . . . 71DDS_DomainParticipant_assert_liveliness . . . 166DDS_DomainParticipant_contains_entity . . . . 167DDS_DomainParticipant_create_contentfilteredto

pic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168DDS_DomainParticipant_create_multitopic . . 169DDS_DomainParticipant_create_publisher . . . 171DDS_DomainParticipant_create_subscriber . . 174DDS_DomainParticipant_create_topic . . . . . . 177DDS_DomainParticipant_delete_contained_entiti

es . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179DDS_DomainParticipant_delete_contentfilteredto

pic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181DDS_DomainParticipant_delete_multitopic . . 183DDS_DomainParticipant_delete_publisher . . . 184DDS_DomainParticipant_delete_subscriber . . 185DDS_DomainParticipant_delete_topic . . . . . . 186DDS_DomainParticipant_enable (inherited) . . 188DDS_DomainParticipant_find_topic . . . . . . . . 188DDS_DomainParticipant_get_builtin_subscriber .

190DDS_DomainParticipant_get_current_time . . 190DDS_DomainParticipant_get_default_publisher_

qos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192DDS_DomainParticipant_get_default_subscriber_

qos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193DDS_DomainParticipant_get_default_topic_qos .

195DDS_DomainParticipant_get_discovered_particip

ant_data . . . . . . . . . . . . . . . . . . . . . . . . . . . 198DDS_DomainParticipant_get_discovered_particip

ants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196DDS_DomainParticipant_get_discovered_topic_d

ata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201DDS_DomainParticipant_get_discovered_topics .

199DDS_DomainParticipant_get_domain_id . . . . 202DDS_DomainParticipant_get_listener . . . . . . . 203DDS_DomainParticipant_get_qos . . . . . . . . . . 204DDS_DomainParticipant_get_status_changes

(inherited) . . . . . . . . . . . . . . . . . . . . . . . . . 205DDS_DomainParticipant_get_statuscondition

(inherited) . . . . . . . . . . . . . . . . . . . . . . . . . 205DDS_DomainParticipant_ignore_participant . 205

683C Reference Guide

Index

DDS_DomainParticipant_ignore_publication 206DDS_DomainParticipant_ignore_subscription 206DDS_DomainParticipant_ignore_topic . . . . . 206DDS_DomainParticipant_lookup_topicdescriptio

n . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206DDS_DomainParticipant_set_default_publisher_q

os . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207DDS_DomainParticipant_set_default_subscriber_

qos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209DDS_DomainParticipant_set_default_topic_qos .

210DDS_DomainParticipant_set_listener . . . . . . 212DDS_DomainParticipant_set_qos. . . . . . . . . . 215DDS_DomainParticipantFactory_create_participa

nt. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221DDS_DomainParticipantFactory_delete_participa

nt. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225DDS_DomainParticipantFactory_get_default_part

icipant_qos . . . . . . . . . . . . . . . . . . . . . . . . 226DDS_DomainParticipantFactory_get_instance 227DDS_DomainParticipantFactory_lookup_particip

ant. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229DDS_DomainParticipantFactory_set_default_part

icipant_qos . . . . . . . . . . . . . . . . . . . . . . . . 230DDS_DomainParticipantListener . . . . . . . . . . . 27DDS_DomainParticipantListener interface. . . 239DDS_DomainParticipantListener__alloc . . . . 242DDS_DomainParticipantListener_on_data_availa

ble (inherited, abstract) . . . . . . . . . . . . . . 243DDS_DomainParticipantListener_on_data_on_rea

ders (inherited, abstract). . . . . . . . . . . . . . 243DDS_DomainParticipantListener_on_inconsistent

_topic (inherited, abstract) . . . . . . . . . . . . 243DDS_DomainParticipantListener_on_liveliness_c

hanged (inherited, abstract) . . . . . . . . . . . 243DDS_DomainParticipantListener_on_liveliness_l

ost (inherited, abstract). . . . . . . . . . . . . . . 244DDS_DomainParticipantListener_on_offered_dea

dline_missed (inherited, abstract) . . . . . . 244DDS_DomainParticipantListener_on_offered_inc

ompatible_qos (inherited, abstract) . . . . . 244DDS_DomainParticipantListener_on_publication

_match (inherited, abstract) . . . . . . . . . . . 245DDS_DomainParticipantListener_on_requested_d

eadline_missed (inherited, abstract). . . . . 245

DDS_DomainParticipantListener_on_requested_incompatible_qos (inherited, abstract) . . . 245

DDS_DomainParticipantListener_on_sample_lost (inherited, abstract) . . . . . . . . . . . . . . . . . 246

DDS_DomainParticipantListener_on_sample_rejected (inherited, abstract) . . . . . . . . . . . . . 246

DDS_DomainParticipantListener_on_subscription_match (inherited, abstract) . . . . . . . . . . . 246

DDS_DomainParticipantQos . . . . . . . . . . . . . 585DDS_DurabilityQosPolicy . . . . . . . . . . . . . . . . 73DDS_DurabilityServiceQosPolicy . . . . . . . . . . 76DDS_Entity_enable . . . . . . . . . . . . . . . . . . . . . 54DDS_Entity_get_instance_handle . . . . . . . . . . 55DDS_Entity_get_listener (abstract) . . . . . . . . . 56DDS_Entity_get_qos (abstract) . . . . . . . . . . . . 56DDS_Entity_get_status_changes . . . . . . . . . . . 57DDS_Entity_get_statuscondition . . . . . . . . . . . 58DDS_Entity_set_listener (abstract). . . . . . . . . . 59DDS_Entity_set_qos (abstract). . . . . . . . . . . . . 59DDS_EntityFactoryQosPolicy . . . . . . . . . . . . . 79DDS_free . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21DDS_GroupDataQosPolicy . . . . . . . . . . . . . . . 80DDS_GuardCondition__alloc. . . . . . . . . . . . . 146DDS_GuardCondition_get_trigger_value

(inherited). . . . . . . . . . . . . . . . . . . . . . . . . 147DDS_GuardCondition_set_trigger_value. . . . 147DDS_HistoryQosPolicy . . . . . . . . . . . . . . . . . . 80DDS_InconsistentTopicStatus . . . . . . . . . . . . 122DDS_LatencyBudgetQosPolicy . . . . . . . . . . . . 83DDS_LifespanQosPolicy . . . . . . . . . . . . . . . . . 84DDS_Listener interface. . . . . . . . . . . . . . . . . . 116DDS_LivelinessChangedStatus . . . . . . . . . . . 122DDS_LivelinessLostStatus . . . . . . . . . . . . . . . 124DDS_LivelinessQosPolicy . . . . . . . . . . . . . 85, 87DDS_MultiTopic_get_expression_parameters 274DDS_MultiTopic_get_name (inherited) . . . . . 275DDS_MultiTopic_get_participant (inherited). 276DDS_MultiTopic_get_subscription_expression. .

276DDS_MultiTopic_get_type_name (inherited) 277DDS_MultiTopic_set_expression_parameters 277DDS_OfferedDeadlineMissedStatus . . . . . . . 125DDS_OfferedIncompatibleQosStatus . . . . . . . 126DDS_OwnershipQosPolicy . . . . . . . . . . . 87, 631DDS_OwnershipStrengthQosPolicy. . . . . . . . . 90

684C Reference Guide

Index

DDS_PARTICIPANT_QOS_DEFAULT 586, 587DDS_PartitionQosPolicy . . . . . . . . . . . . . . . . . . 91DDS_PresentationQosPolicy . . . . . . . . . . . . . . . 92DDS_PublicationMatchStatus . . . . . . . . . . . . . 128DDS_Publisher_begin_coherent_changes . . . . 292DDS_Publisher_copy_from_topic_qos . . . . . . 294DDS_Publisher_create_datawriter . . . . . . . . . . 295DDS_Publisher_delete_contained_entities . . . 299DDS_Publisher_delete_datawriter . . . . . . . . . . 300DDS_Publisher_enable (inherited). . . . . . . . . . 301DDS_Publisher_end_coherent_changes. . . . . . 301DDS_Publisher_get_default_datawriter_qos . . 302DDS_Publisher_get_listener . . . . . . . . . . . . . . 304DDS_Publisher_get_participant . . . . . . . . . . . . 304DDS_Publisher_get_qos. . . . . . . . . . . . . . . . . . 305DDS_Publisher_get_status_changes (inherited) . .

306DDS_Publisher_get_statuscondition (inherited) . .

306DDS_Publisher_lookup_datawriter . . . . . . . . . 306DDS_PUBLISHER_QOS_DEFAULT . . . . . . 589DDS_Publisher_resume_publications . . . . . . . 307DDS_Publisher_set_default_datawriter_qos . . 308DDS_Publisher_set_listener. . . . . . . . . . . . . . . 310DDS_Publisher_set_qos . . . . . . . . . . . . . . . . . . 312DDS_Publisher_suspend_publications. . . . . . . 314DDS_PublisherListener . . . . . . . . . . . . . . . . . . . 34DDS_PublisherListener interface. . . . . . . . . . . 380DDS_PublisherListener__alloc . . . . . . . . . . . . 383DDS_PublisherListener_on_liveliness_lost

(inherited, abstract) . . . . . . . . . . . . . . . . . . 383DDS_PublisherListener_on_offered_deadline_mi

ssed (inherited, abstract) . . . . . . . . . . . . . . 384DDS_PublisherListener_on_offered_incompatible

_qos (inherited, abstract) . . . . . . . . . . . . . . 384DDS_PublisherListener_on_publication_match

(inherited, abstract) . . . . . . . . . . . . . . . . . . 384DDS_PublisherQos. . . . . . . . . . . . . . . . . . . . . . 588DDS_QueryCondition_get_datareader (inherited).

530DDS_QueryCondition_get_instance_state_mask

(inherited) . . . . . . . . . . . . . . . . . . . . . . . . . 530DDS_QueryCondition_get_query_arguments .531DDS_QueryCondition_get_query_expression .532DDS_QueryCondition_get_sample_state_mask

(inherited) . . . . . . . . . . . . . . . . . . . . . . . . . 532DDS_QueryCondition_get_trigger_value

(inherited) . . . . . . . . . . . . . . . . . . . . . . . . . 533DDS_QueryCondition_get_view_state_mask

(inherited) . . . . . . . . . . . . . . . . . . . . . . . . . 533DDS_QueryCondition_set_query_arguments . 533DDS_ReadCondition_get_datareader . . . . . . . 526DDS_ReadCondition_get_instance_state_mask . .

526DDS_ReadCondition_get_sample_state_mask 527DDS_ReadCondition_get_trigger_value

(inherited) . . . . . . . . . . . . . . . . . . . . . . . . . 528DDS_ReadCondition_get_view_state_mask . . 528DDS_ReaderDataLifecycleQosPolicy . . . . . . . . 99DDS_ReliabilityQosPolicy . . . . . . . . . . . . . . . 102DDS_RequestedDeadlineMissedStatus . . . . . . 129DDS_RequestedIncompatibleQosStatus . . . . . 130DDS_ResourceLimitsQosPolicy . . . . . . . . . . . 104DDS_SampleInfo . . . . . . . . . . . . . . . . . . . . . . . 506DDS_SampleLostStatus . . . . . . . . . . . . . . . . . . 132DDS_SampleRejectedStatus . . . . . . . . . . . . . . 133DDS_sequence_get_release . . . . . . . . . . . . . . . . 17DDS_sequence_set_release . . . . . . . . . . . . . . . . 16DDS_StatusCondition_get_enabled_statuses . 149DDS_StatusCondition_get_entity . . . . . . . . . . 151DDS_StatusCondition_get_trigger_value

(inherited) . . . . . . . . . . . . . . . . . . . . . . . . . 151DDS_StatusCondition_set_enabled_statuses. . 152DDS_string_alloc . . . . . . . . . . . . . . . . . . . . . . . . 20DDS_Subscriber. . . . . . . . . . . . . . . . . . . . . . . . 645DDS_Subscriber Statecraft for a Read

Communication Status . . . . . . . . . . . . . . . 646DDS_Subscriber_begin_access . . . . . . . . . . . . 395DDS_Subscriber_copy_from_topic_qos . . . . . 396DDS_Subscriber_create_datareader. . . . . . . . . 398DDS_Subscriber_delete_contained_entities . . 401DDS_Subscriber_delete_datareader. . . . . . . . . 403DDS_Subscriber_enable (inherited) . . . . . . . . 404DDS_Subscriber_end_access. . . . . . . . . . . . . . 405DDS_Subscriber_get_datareaders . . . . . . . . . . 406DDS_Subscriber_get_default_datareader_qos. 408DDS_Subscriber_get_listener . . . . . . . . . . . . . 409DDS_Subscriber_get_participant. . . . . . . . . . . 410DDS_Subscriber_get_qos . . . . . . . . . . . . . . . . 411DDS_Subscriber_get_status_changes (inherited) .

685C Reference Guide

Index

412DDS_Subscriber_get_statuscondition (inherited).

412DDS_Subscriber_lookup_datareader . . . . . . . 412DDS_Subscriber_notify_datareaders . . . . . . . 413DDS_SUBSCRIBER_QOS_DEFAULT . . . 590DDS_Subscriber_set_default_datareader_qos 414DDS_Subscriber_set_listener . . . . . . . . . . . . . 416DDS_Subscriber_set_qos . . . . . . . . . . . . . . . . 419DDS_SubscriberListener. . . . . . . . . . . . . . . . . . 36DDS_SubscriberListener__alloc . . . . . . . . . . . 512DDS_SubscriberListener_on_data_available

(inherited, abstract) . . . . . . . . . . . . . . . . . 513DDS_SubscriberListener_on_data_on_readers

(abstract). . . . . . . . . . . . . . . . . . . . . . . . . . 513DDS_SubscriberListener_on_liveliness_changed

(inherited, abstract) . . . . . . . . . . . . . . . . . 514DDS_SubscriberListener_on_requested_deadline

_missed (inherited, abstract) . . . . . . . . . . 514DDS_SubscriberListener_on_requested_incompat

ible_qos (inherited, abstract) . . . . . . . . . . 515DDS_SubscriberListener_on_sample_lost

(inherited, abstract) . . . . . . . . . . . . . . . . . 515DDS_SubscriberListener_on_sample_rejected

(inherited, abstract) . . . . . . . . . . . . . . . . . 515DDS_SubscriberListener_on_subscription_match

(inherited, abstract) . . . . . . . . . . . . . . . . . 515DDS_SubscriberQos . . . . . . . . . . . . . . . . . . . . 589DDS_SubscriptionMatchStatus. . . . . . . . . . . . 134DDS_TimeBasedFilterQosPolicy . . . . . . . . . . 107DDS_Topic Definition Example . . . . . . . . . . . 653DDS_Topic_enable (inherited) . . . . . . . . . . . . 259DDS_Topic_get_inconsistent_topic_status . . 260DDS_Topic_get_listener . . . . . . . . . . . . . . . . . 261

DDS_Topic_get_name (inherited) . . . . . . . . . 261DDS_Topic_get_participant (inherited) . . . . . 261DDS_Topic_get_qos. . . . . . . . . . . . . . . . . . . . 262DDS_Topic_get_status_changes (inherited). . 263DDS_Topic_get_statuscondition (inherited) . 263DDS_Topic_get_type_name (inherited) . . . . . 263DDS_TOPIC_QOS_DEFAULT. . . . . . . . . . . 592DDS_Topic_set_listener . . . . . . . . . . . . . . . . . 263DDS_Topic_set_qos . . . . . . . . . . . . . . . . . . . . 265DDS_TopicDataQosPolicy . . . . . . . . . . . . . . . 108DDS_TopicDescription_get_name . . . . . . . . . 256DDS_TopicDescription_get_participant. . . . . 256DDS_TopicDescription_get_type_name . . . . 257DDS_TopicListener . . . . . . . . . . . . . . . . . . . . . 32DDS_TopicListener interface . . . . . . . . . . . . . 278DDS_TopicListener__alloc . . . . . . . . . . . . . . 279DDS_TopicListener_on_inconsistent_topic

(abstract) . . . . . . . . . . . . . . . . . . . . . . . . . 280DDS_TopicQos. . . . . . . . . . . . . . . . . . . . . . . . 590DDS_TransportPriorityQosPolicy . . . . . . . . . 109DDS_TypeSupport__alloc (abstract) . . . . . . . 284DDS_TypeSupport_get_type_name (abstract) 284DDS_TypeSupport_register_type (abstract). . 284DDS_UserDataQosPolicy. . . . . . . . . . . . . . . . 110DDS_WaitSet__alloc . . . . . . . . . . . . . . . . . . . 137DDS_WaitSet_attach_condition . . . . . . . . . . . 137DDS_WaitSet_detach_condition . . . . . . . . . . 139DDS_WaitSet_get_conditions . . . . . . . . . . . . 140DDS_WaitSet_wait . . . . . . . . . . . . . . . . . . . . . 141DDS_WriterDataLifecycleQosPolicy. . . . . . . 110Default attributes. . . . . . . . . . . . . . . . . . . . . . . . 65Document Structure . . . . . . . . . . . . . . . . . . . . . . 3Domain Module . . . . . . . . . . . . . . . . . . . . 43, 161

FFunctionality . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

IIDL Mapping Rules for Sequences . . . . . . . . . . . 9IDL Pre-processor . . . . . . . . . . . . . . . . . . . . . . 654IDL to Host Language Mapping . . . . . . . . . . . 654

Infrastructure Module . . . . . . . . . . . . . . . . . 42, 52Inheritance of Abstract Operations . . . . . . . . . . 40instance_state . . . . . . . . . . . . . . . . . . . . . . . . . 631

686C Reference Guide

Index

LListeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646 Listeners Interfaces . . . . . . . . . . . . . . . . . . . . . . 22

MMemory Management . . . . . . . . . . . . . . . . . . . . . 9

OOperations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Operations Concerning States . . . . . . . . . . . . . 635

PPlain Communication Status State Chart . . . . . 644Plain Sequences . . . . . . . . . . . . . . . . . . . . . . . . . 11Pre-defined Bit Mask Definitions. . . . . . . . . . . 634Pre-processor Generation of the Typed Classes for

Data Type “Foo” . . . . . . . . . . . . . . . . . . . . 255Publication Module . . . . . . . . . . . . . . . . . . 46, 289Publication Type Specific Classes . . . . . . . . . . 317

QQosPolicy Basics . . . . . . . . . . . . . . . . . . . . . . . 67QosPolicy Default Attributes . . . . . . . . . . . . . . 65

QosPolicy Objects . . . . . . . . . . . . . . . . . . . . . . . 12QosPolicy Settings . . . . . . . . . . . . . . . . . . . . . . . 61

Rread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635Read Communication Status sDDS_DataReader

Statecraft . . . . . . . . . . . . . . . . . . . . . . . . . . 645read_instance . . . . . . . . . . . . . . . . . . . . . . . . . . 637read_next_sample . . . . . . . . . . . . . . . . . . . . . . . 636read_w_condition . . . . . . . . . . . . . . . . . . . . . . . 636Requested Offered PresentationQosPolicy. . . . . 98Requested/Offered . . . . . . . . . . . . . . . . . . . . . . . 61Requested/Offered

DDS_DestinationOrderQosPolicy . . . . . . . 72Requested/Offered DDS_DurabilityQosPolicy . 75Requested/Offered DDS_ReliabilityQosPolicy 89,

104Resources and operations . . . . . . . . . . . . . . . . . . 12Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Return Value . . . . . . . . . . . . . . . . . . . . . . . . . . 299RxO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Ssample_state . . . . . . . . . . . . . . . . . . . . . . . . . . . 629SampleInfo Class . . . . . . . . . . . . . . . . . . . . . . . 629Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Sequences DDS_ . . . . . . . . . . . . . . . . . . . . . . . . 13Sequences Embeded in QosPolicy Objects . . . . 12Sequences Embeded in Status Objects . . . . . . . . 12Signal Handling . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Snapshot . . . . . . . . . . . . . . . . . . . . . . . . . . 632, 633SPACE_FooDataReader_create_querycondition

(inherited) . . . . . . . . . . . . . . . . . . . . . . . . . 471SPACE_FooDataReader_create_readcondition

(inherited) . . . . . . . . . . . . . . . . . . . . . . . . . 471SPACE_FooDataReader_delete_contained_entitie

s (inherited) . . . . . . . . . . . . . . . . . . . . . . . . 472

687C Reference Guide

Index

SPACE_FooDataReader_delete_readcondition (inherited). . . . . . . . . . . . . . . . . . . . . . . . . 472

SPACE_FooDataReader_enable (inherited) . . 472SPACE_FooDataReader_get_key_value . . . . 472SPACE_FooDataReader_get_listener (inherited).

474SPACE_FooDataReader_get_liveliness_changed_

status (inherited). . . . . . . . . . . . . . . . . . . . 474SPACE_FooDataReader_get_matched_publicatio

n_data (inherited) . . . . . . . . . . . . . . . . . . . 474SPACE_FooDataReader_get_matched_publicatio

ns (inherited) . . . . . . . . . . . . . . . . . . . . . . 474SPACE_FooDataReader_get_qos (inherited) . 475SPACE_FooDataReader_get_requested_deadline

_missed_status (inherited) . . . . . . . . . . . . 475SPACE_FooDataReader_get_requested_incompat

ible_qos_status (inherited) . . . . . . . . . . . . 475SPACE_FooDataReader_get_sample_lost_status

(inherited). . . . . . . . . . . . . . . . . . . . . . . . . 476SPACE_FooDataReader_get_sample_rejected_sta

tus (inherited) . . . . . . . . . . . . . . . . . . . . . . 476SPACE_FooDataReader_get_status_changes

(inherited). . . . . . . . . . . . . . . . . . . . . . . . . 476SPACE_FooDataReader_get_statuscondition

(inherited). . . . . . . . . . . . . . . . . . . . . . . . . 476SPACE_FooDataReader_get_subscriber

(inherited). . . . . . . . . . . . . . . . . . . . . . . . . 477SPACE_FooDataReader_get_subscription_match

_status (inherited). . . . . . . . . . . . . . . . . . . 477SPACE_FooDataReader_get_topicdescription

(inherited). . . . . . . . . . . . . . . . . . . . . . . . . 477SPACE_FooDataReader_read . . . . . . . . . . . . 478SPACE_FooDataReader_read_instance . . . . . 483SPACE_FooDataReader_read_next_instance 485SPACE_FooDataReader_read_next_instance_w_

condition. . . . . . . . . . . . . . . . . . . . . . . . . . 488SPACE_FooDataReader_read_next_sample . 490SPACE_FooDataReader_read_w_condition . 490SPACE_FooDataReader_return_loan. . . . . . . 492SPACE_FooDataReader_set_listener (inherited) .

494SPACE_FooDataReader_set_qos (inherited) . 495SPACE_FooDataReader_take. . . . . . . . . . . . . 495SPACE_FooDataReader_take_instance . . . . . 497SPACE_FooDataReader_take_next_sample . 503

SPACE_FooDataReader_take_w_condition . 503SPACE_FooDataReader_wait_for_historical_data

(inherited). . . . . . . . . . . . . . . . . . . . . . . . . 505SPACE_FooDataWriter_assert_liveliness

(inherited). . . . . . . . . . . . . . . . . . . . . . . . . 349SPACE_FooDataWriter_dispose . . . . . . . . . . 349SPACE_FooDataWriter_dispose_w_timestamp .

353, . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380SPACE_FooDataWriter_enable (inherited) . . 355SPACE_FooDataWriter_get_key_value. . . . . 355SPACE_FooDataWriter_get_listener (inherited) .

356SPACE_FooDataWriter_get_liveliness_lost_statu

s (inherited) . . . . . . . . . . . . . . . . . . . . . . . 357SPACE_FooDataWriter_get_matched_subscriptio

n_data (inherited) . . . . . . . . . . . . . . . . . . . 357SPACE_FooDataWriter_get_matched_subscriptio

ns (inherited) . . . . . . . . . . . . . . . . . . . . . . 357SPACE_FooDataWriter_get_offered_deadline_mi

ssed_status (inherited) . . . . . . . . . . . . . . . 357SPACE_FooDataWriter_get_offered_incompatibl

e_qos_status (inherited) . . . . . . . . . . . . . . 358SPACE_FooDataWriter_get_publication_match_s

tatus (inherited) . . . . . . . . . . . . . . . . . . . . 358SPACE_FooDataWriter_get_publisher (inherited)

358SPACE_FooDataWriter_get_qos (inherited) . 358SPACE_FooDataWriter_get_status_changes

(inherited). . . . . . . . . . . . . . . . . . . . . . . . . 359SPACE_FooDataWriter_get_statuscondition

(inherited). . . . . . . . . . . . . . . . . . . . . . . . . 359SPACE_FooDataWriter_get_topic (inherited) 359SPACE_FooDataWriter_register_instance. . . 359SPACE_FooDataWriter_register_instance_w_tim

estamp . . . . . . . . . . . . . . . . . . . . . . . . . . . 363SPACE_FooDataWriter_set_listener (inherited) .

364SPACE_FooDataWriter_set_qos (inherited) . 365SPACE_FooDataWriter_unregister_instance. 365SPACE_FooDataWriter_unregister_instance_w_ti

mestamp . . . . . . . . . . . . . . . . . . . . . . . . . . 369SPACE_FooDataWriter_write . . . . . . . . . . . . 371SPACE_FooDataWriter_write_w_timestamp 375SPACE_FooTypeSupport__alloc . . . . . . . . . . 285SPACE_FooTypeSupport_get_type_name. . . 286

688C Reference Guide

Index

SPACE_FooTypeSupport_register_type . . . . . 287SQL Examples . . . . . . . . . . . . . . . . . . . . . . . . . 661SQL Grammar in BNF . . . . . . . . . . . . . . . . . . . 659SQL Token Expression. . . . . . . . . . . . . . . . . . . 660Standard Defined Type. . . . . . . . . . . . . . . . . . . . 10State Chart of the instance_state for a Single

Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . 632State Chart of the sample_state for a Single Sample

630State Chart of the view_state for a Single Instance

633State Definitions . . . . . . . . . . . . . . . . . . . . . . . .634

State Masks . . . . . . . . . . . . . . . . . . . . . . . . . . . 634State per Sample. . . . . . . . . . . . . . . . . . . . . . . . 630Status Description Per DDS_Entity . . . . . . . . 118Status Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . 12Status Per DDS_Entity . . . . . . . . . . . . . . . . . . . 148Struct DDS_Listener . . . . . . . . . . . . . . . . . . . . . 24Struct DDS_SampleInfo. . . . . . . . . . . . . . . . . . 506Struct DDS_Status . . . . . . . . . . . . . . . . . . . . . . 117Struct QosPolicy. . . . . . . . . . . . . . . . . . . . . . . . . 59Subscription Module . . . . . . . . . . . . . . . . . 48, 391Subscription Type Specific Classes . . . . . . . . . 420

Ttake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636take_next_instance . . . . . . . . . . . . . . . . . . . . . . 499take_next_sample . . . . . . . . . . . . . . . . . . . . . . . 636take_w_condition . . . . . . . . . . . . . . . . . . . . . . . 636The DCPS Publication Module’s Class Model 289The DCPS Subscription Module’s Class Model . .

391

Thread Safety . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Topic-Definition Module . . . . . . . . . . . . . . 44, 254Topic-Definition type specific classes . . . . . . . 283Trigger State of the DDS_GuardCondition . . . 652Trigger State of the DDS_ReadCondition and

DDS_QueryCondition. . . . . . . . . . . . . . . . 651Trigger State of the DDS_StatusCondition . . . 651

UUser Defined Type . . . . . . . . . . . . . . . . . . . . . . . 10

Vview_state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632

689C Reference Guide

Index

690C Reference Guide