RTI Connext .NET API (legacy)  Version 6.1.2
DDS::Topic Class Reference

<<interface>> The most basic description of the data to be published and subscribed. More...

#include <managed_topic.h>

Inheritance diagram for DDS::Topic:
DDS::DomainEntity DDS::ITopicDescription DDS::Entity

Public Member Functions

void get_inconsistent_topic_status (InconsistentTopicStatus% status)
 Allows the application to retrieve the INCONSISTENT_TOPIC_STATUS status of a DDS::Topic. More...
 
void set_qos (TopicQos^ qos)
 Set the topic QoS. More...
 
void set_qos_with_profile (System::String^ library_name, System::String^ profile_name)
 <<extension>> Change the QoS of this topic using the input XML QoS profile. More...
 
void get_qos (TopicQos^ qos)
 Get the topic QoS. More...
 
void set_listener (TopicListener^ l, StatusMask mask)
 Set the topic listener. More...
 
TopicListenerget_listener ()
 Get the topic listener. More...
 
virtual System::String ^ get_type_name ()
 Get the associated type_name. More...
 
virtual System::String ^ get_name ()
 Get the name used to create this ITopicDescription . More...
 
virtual DomainParticipantget_participant ()
 Get the DDS::DomainParticipant to which the ITopicDescription belongs. More...
 
virtual void enable () override
 Enables the DDS::Entity. More...
 
virtual StatusConditionget_statuscondition () override
 Allows access to the DDS::StatusCondition associated with the DDS::Entity. More...
 
virtual StatusMask get_status_changes () override
 Retrieves the list of communication statuses in the DDS::Entity that are triggered. More...
 
virtual InstanceHandle_t get_instance_handle () override
 Allows access to the DDS::InstanceHandle_t associated with the DDS::Entity. More...
 

Static Public Member Functions

static Topicnarrow (ITopicDescription^ topic_description)
 Narrow the given ITopicDescription pointer to a DDS::Topic pointer. More...
 

Detailed Description

<<interface>> The most basic description of the data to be published and subscribed.

QoS:
DDS::TopicQos
Status:
INCONSISTENT_TOPIC_STATUS, DDS::InconsistentTopicStatus
Listener:
DDS::TopicListener

A DDS::Topic is identified by its name, which must be unique in the whole domain. In addition (by virtue of extending ITopicDescription) it fully specifies the type of the data that can be communicated when publishing or subscribing to the DDS::Topic.

DDS::Topic is the only ITopicDescription that can be used for publications and therefore associated with a DDS::DataWriter.

The following operations may be called even if the DDS::Topic is not enabled. Other operations will fail with the value DDS::Retcode_NotEnabled if called on a disabled DDS::Topic:

See also
Operations Allowed in Listener Callbacks
Examples:
HelloWorld_publisher.cpp, and HelloWorld_subscriber.cpp.

Member Function Documentation

◆ narrow()

static Topic ^ DDS::Topic::narrow ( ITopicDescription topic_description)
static

Narrow the given ITopicDescription pointer to a DDS::Topic pointer.

Returns
DDS::Topic if this ITopicDescription is a DDS::Topic. Otherwise, return NULL.

◆ get_inconsistent_topic_status()

void DDS::Topic::get_inconsistent_topic_status ( InconsistentTopicStatus status)

Allows the application to retrieve the INCONSISTENT_TOPIC_STATUS status of a DDS::Topic.

Retrieve the current DDS::InconsistentTopicStatus

Parameters
status<<inout>> Status to be retrieved. Cannot be NULL.
Exceptions
Oneof the Standard Return Codes
See also
DDS::InconsistentTopicStatus

◆ set_qos()

void DDS::Topic::set_qos ( TopicQos qos)

Set the topic QoS.

The DDS::TopicQos::topic_data and DDS::TopicQos::deadline, DDS::TopicQos::latency_budget, DDS::TopicQos::transport_priority and DDS::TopicQos::lifespan can be changed. The other policies are immutable.

Parameters
qos<<in>> Set of policies to be applied to DDS::Topic.

Policies must be consistent. Immutable policies cannot be changed after DDS::Topic is enabled. The special value DDS::DomainParticipant::TOPIC_QOS_DEFAULT can be used to indicate that the QoS of the DDS::Topic should be changed to match the current default DDS::TopicQos set in the DDS::DomainParticipant. Cannot be NULL.

Exceptions
Oneof the Standard Return Codes, DDS::Retcode_ImmutablePolicy if immutable policy is changed, or DDS::Retcode_InconsistentPolicy if policies are inconsistent
See also
DDS::TopicQos for rules on consistency among QoS
set_qos (abstract)
Operations Allowed in Listener Callbacks

◆ set_qos_with_profile()

void DDS::Topic::set_qos_with_profile ( System::String^  library_name,
System::String^  profile_name 
)

<<extension>> Change the QoS of this topic using the input XML QoS profile.

The DDS::TopicQos::topic_data and DDS::TopicQos::deadline, DDS::TopicQos::latency_budget, DDS::TopicQos::transport_priority and DDS::TopicQos::lifespan can be changed. The other policies are immutable.

Parameters
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDS::DomainParticipant::set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS::DomainParticipant::set_default_profile).
Exceptions
Oneof the Standard Return Codes, DDS::Retcode_ImmutablePolicy if immutable policy is changed, or DDS::Retcode_InconsistentPolicy if policies are inconsistent
See also
DDS::TopicQos for rules on consistency among QoS
Operations Allowed in Listener Callbacks

◆ get_qos()

void DDS::Topic::get_qos ( TopicQos qos)

Get the topic QoS.

This method may potentially allocate memory depending on the sequences contained in some QoS policies.

Parameters
qos<<inout>> QoS to be filled up. Cannot be NULL.
Exceptions
Oneof the Standard Return Codes
See also
get_qos (abstract)

◆ set_listener()

void DDS::Topic::set_listener ( TopicListener l,
StatusMask  mask 
)

Set the topic listener.

Parameters
l<<in>> Listener to be installed on entity.
mask<<in>> Changes of communication status to be invoked on the listener. See DDS::StatusMask.
Exceptions
Oneof the Standard Return Codes
See also
set_listener (abstract)

◆ get_listener()

TopicListener ^ DDS::Topic::get_listener ( )

Get the topic listener.

Returns
Existing listener attached to the DDS::Topic.
See also
get_listener (abstract)

◆ get_type_name()

virtual System::String ^ DDS::Topic::get_type_name ( )
virtual

Get the associated type_name.

The type name defines a locally unique type for the publication or the subscription.

The type_name corresponds to a unique string used to register a type via the FooTypeSupport::register_type method.

Thus, the type_name implies an association with a corresponding DDS::TypeSupport and this ITopicDescription.

Returns
the type name. The returned type name is valid until the ITopicDescription is deleted.
Postcondition
The result is non-NULL.
See also
DDS::TypeSupport, FooTypeSupport

Implements DDS::ITopicDescription.

◆ get_name()

virtual System::String ^ DDS::Topic::get_name ( )
virtual

Get the name used to create this ITopicDescription .

Returns
the name used to create this ITopicDescription. The returned topic name is valid until the ITopicDescription is deleted.
Postcondition
The result is non-NULL.

Implements DDS::ITopicDescription.

◆ get_participant()

virtual DomainParticipant ^ DDS::Topic::get_participant ( )
virtual

Get the DDS::DomainParticipant to which the ITopicDescription belongs.

Returns
The DDS::DomainParticipant to which the ITopicDescription belongs.
Postcondition
The result is non-NULL.

Implements DDS::ITopicDescription.

◆ enable()

virtual void DDS::Topic::enable ( )
overridevirtual

Enables the DDS::Entity.

This operation enables the Entity. Entity objects can be created either enabled or disabled. This is controlled by the value of the ENTITY_FACTORY QoS policy on the corresponding factory for the DDS::Entity.

By default, ENTITY_FACTORY is set so that it is not necessary to explicitly call DDS::Entity::enable on newly created entities.

The DDS::Entity::enable operation is idempotent. Calling enable on an already enabled Entity returns OK and has no effect.

If a DDS::Entity has not yet been enabled, the following kinds of operations may be invoked on it:

Other operations may explicitly state that they may be called on disabled entities; those that do not will return the error DDS::Retcode_NotEnabled.

It is legal to delete an DDS::Entity that has not been enabled by calling the proper operation on its factory.

Entities created from a factory Entity that is disabled are created disabled, regardless of the setting of the DDS::EntityFactoryQosPolicy.

Calling enable on an Entity whose factory Entity is not enabled will fail and return DDS::Retcode_PreconditionNotMet.

If DDS::EntityFactoryQosPolicy::autoenable_created_entities is TRUE, the enable operation on a factory will automatically enable all entities created from that factory (for example, enabling a DDS::Publisher will enable all its contained DDS::DataWriter objects)

Listeners associated with an entity are not called until the entity is enabled.

Conditions associated with a disabled entity are "inactive," that is, they have a trigger_value == FALSE.

Exceptions
Oneof the Standard Return Codes, Standard Return Codes or DDS::Retcode_PreconditionNotMet.

Implements DDS::Entity.

◆ get_statuscondition()

virtual StatusCondition ^ DDS::Topic::get_statuscondition ( )
overridevirtual

Allows access to the DDS::StatusCondition associated with the DDS::Entity.

The returned condition can then be added to a DDS::WaitSet so that the application can wait for specific status changes that affect the DDS::Entity.

Returns
the status condition associated with this entity.

Implements DDS::Entity.

◆ get_status_changes()

virtual StatusMask DDS::Topic::get_status_changes ( )
overridevirtual

Retrieves the list of communication statuses in the DDS::Entity that are triggered.

That is, the list of statuses whose value has changed since the last time the application read the status using the get_*_status() method.

When the entity is first created or if the entity is not enabled, all communication statuses are in the "untriggered" state so the list returned by the get_status_changes operation will be empty.

The list of statuses returned by the get_status_changes operation refers to the status that are triggered on the Entity itself and does not include statuses that apply to contained entities.

Returns
list of communication statuses in the DDS::Entity that are triggered.
See also
Status Kinds

Implements DDS::Entity.

◆ get_instance_handle()

virtual InstanceHandle_t DDS::Topic::get_instance_handle ( )
overridevirtual

Allows access to the DDS::InstanceHandle_t associated with the DDS::Entity.

This operation returns the DDS::InstanceHandle_t that represents the DDS::Entity.

Returns
the instance handle associated with this entity.

Implements DDS::Entity.