RTI Connext .NET API (legacy)
Version 6.1.2
|
<<interface>> A publisher is the object responsible for the actual dissemination of publications. More...
#include <managed_publication.h>
Public Member Functions | |
void | get_default_datawriter_qos (DataWriterQos^ qos) |
Copies the default DDS::DataWriterQos values into the provided DDS::DataWriterQos instance. More... | |
void | set_default_datawriter_qos (DataWriterQos^ qos) |
Sets the default DDS::DataWriterQos values for this publisher. More... | |
void | set_default_datawriter_qos_with_profile (System::String^ library_name, System::String^ profile_name) |
<<extension>> Set the default DDS::DataWriterQos values for this publisher based on the input XML QoS profile. More... | |
void | set_default_library (System::String^ library_name) |
<<extension>> Sets the default XML library for a DDS::Publisher. More... | |
System::String ^ | get_default_library () |
<<extension>> Gets the default XML library associated with a DDS::Publisher. More... | |
void | set_default_profile (System::String^ library_name, System::String^ profile_name) |
<<extension>> Sets the default XML profile for a DDS::Publisher. More... | |
System::String ^ | get_default_profile () |
<<extension>> Gets the default XML profile associated with a DDS::Publisher. More... | |
System::String ^ | get_default_profile_library () |
<<extension>> Gets the library where the default XML QoS profile is contained for a DDS::Publisher. More... | |
DataWriter ^ | create_datawriter (Topic^ topic, DataWriterQos^ qos, DataWriterListener^ listener, StatusMask mask) |
Creates a DDS::DataWriter that will be attached and belong to the DDS::Publisher. More... | |
DataWriter ^ | create_datawriter_with_profile (Topic^ topic, System::String^ library_name, System::String^ profile_name, DataWriterListener^ listener, StatusMask mask) |
<<extension>> Creates a DDS::DataWriter object using the DDS::DataWriterQos associated with the input XML QoS profile. More... | |
void | delete_datawriter (DataWriter^% a_datawriter) |
Deletes a DDS::DataWriter that belongs to the DDS::Publisher. More... | |
DataWriter ^ | lookup_datawriter (System::String^ topic_name) |
Retrieves the DDS::DataWriter for a specific DDS::Topic. More... | |
void | suspend_publications () |
Indicates to RTI Connext that the application is about to make multiple modifications using DDS::DataWriter objects belonging to the DDS::Publisher. More... | |
void | resume_publications () |
Indicates to RTI Connext that the application has completed the multiple changes initiated by the previous DDS::Publisher::suspend_publications. More... | |
void | begin_coherent_changes () |
Indicates that the application will begin a coherent set of modifications using DDS::DataWriter objects attached to the DDS::Publisher. More... | |
void | end_coherent_changes () |
Terminates the coherent set initiated by the matching call to DDS::Publisher::begin_coherent_changes. More... | |
void | get_all_datawriters (DataWriterSeq^ writers) |
Retrieve all the DataWriters created from this Publisher. More... | |
DomainParticipant ^ | get_participant () |
Returns the DDS::DomainParticipant to which the DDS::Publisher belongs. More... | |
void | delete_contained_entities () |
Deletes all the entities that were created by means of the "create" operation on the DDS::Publisher. More... | |
void | copy_from_topic_qos (DataWriterQos^ a_datawriter_qos, TopicQos^ a_topic_qos) |
Copies the policies in the DDS::TopicQos to the corresponding policies in the DDS::DataWriterQos. More... | |
void | wait_for_acknowledgments (Duration_t max_wait) |
Blocks the calling thread until all data written by the Publisher's reliable DataWriters is acknowledged, or until timeout expires. More... | |
void | wait_for_asynchronous_publishing (Duration_t max_wait) |
<<extension>> Blocks the calling thread until asynchronous sending is complete. More... | |
void | set_qos (PublisherQos^ qos) |
Sets the publisher QoS. More... | |
void | set_qos_with_profile (System::String^ library_name, System::String^ profile_name) |
<<extension>> Change the QoS of this publisher using the input XML QoS profile. More... | |
void | get_qos (PublisherQos^ qos) |
Gets the publisher QoS. More... | |
void | set_listener (PublisherListener^ l, StatusMask mask) |
Sets the publisher listener. More... | |
PublisherListener ^ | get_listener () |
Get the publisher listener. More... | |
virtual void | enable () override |
Enables the DDS::Entity. More... | |
virtual StatusCondition ^ | get_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... | |
DataWriter ^ | lookup_datawriter_by_name (String^ datawriter_name) |
<<extension>> Retrieves a DDS::DataWriter contained within the DDS::Publisher the DDS::DataWriter entity name. More... | |
Properties | |
static DataWriterQos^ | DATAWRITER_QOS_DEFAULT [get] |
Special value for creating DDS::DataWriter with default QoS. More... | |
static DataWriterQos^ | DATAWRITER_QOS_PRINT_ALL [get] |
Special value which can be supplied to DDS::DataWriterQos::ToString(DDS::DataWriterQos^ baseQos, DDS::QosPrintFormat^ format) indicating that all of the QoS should be printed. More... | |
static DataWriterQos^ | DATAWRITER_QOS_USE_TOPIC_QOS [get] |
Special value for creating DDS::DataWriter with a combination of the default DDS::DataWriterQos and the DDS::TopicQos. More... | |
<<interface>> A publisher is the object responsible for the actual dissemination of publications.
A publisher acts on the behalf of one or several DDS::DataWriter objects that belong to it. When it is informed of a change to the data associated with one of its DDS::DataWriter objects, it decides when it is appropriate to actually send the data-update message. In making this decision, it considers any extra information that goes with the data (timestamp, writer, etc.) as well as the QoS of the DDS::Publisher and the DDS::DataWriter.
The following operations may be called even if the DDS::Publisher is not enabled. Other operations will fail with the value DDS::Retcode_NotEnabled if called on a disabled DDS::Publisher:
void DDS::Publisher::get_default_datawriter_qos | ( | DataWriterQos^ | qos | ) |
Copies the default DDS::DataWriterQos values into the provided DDS::DataWriterQos instance.
The retrieved qos
will match the set of values specified on the last successful call to DDS::Publisher::set_default_datawriter_qos or DDS::Publisher::set_default_datawriter_qos_with_profile, or else, if the call was never made, the default values from its owning DDS::DomainParticipant.
This method may potentially allocate memory depending on the sequences contained in some QoS policies.
qos | <<inout>> DDS::DataWriterQos to be filled-up. Cannot be NULL. |
One | of the Standard Return Codes |
void DDS::Publisher::set_default_datawriter_qos | ( | DataWriterQos^ | qos | ) |
Sets the default DDS::DataWriterQos values for this publisher.
This call causes the default values inherited from the owning DDS::DomainParticipant to be overridden.
This default value will be used for newly created DDS::DataWriter if DDS::Publisher::DATAWRITER_QOS_DEFAULT is specified as the qos
parameter when DDS::Publisher::create_datawriter is called.
qos
parameter. qos | <<in>> Default qos to be set. The special value DDS::Subscriber::DATAREADER_QOS_DEFAULT may be passed as qos to indicate that the default QoS should be reset back to the initial values the factory would used if DDS::Publisher::set_default_datawriter_qos had never been called. Cannot be NULL. |
One | of the Standard Return Codes, or DDS::Retcode_InconsistentPolicy |
void DDS::Publisher::set_default_datawriter_qos_with_profile | ( | System::String^ | library_name, |
System::String^ | profile_name | ||
) |
<<extension>> Set the default DDS::DataWriterQos values for this publisher based on the input XML QoS profile.
This default value will be used for newly created DDS::DataWriter if DDS::Publisher::DATAWRITER_QOS_DEFAULT is specified as the qos
parameter when DDS::Publisher::create_datawriter is called.
qos
parameter. library_name | <<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDS::Publisher::set_default_library). |
profile_name | <<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS::Publisher::set_default_profile). |
If the input profile cannot be found, the method fails with DDS::Retcode_Error.
One | of the Standard Return Codes, or DDS::Retcode_InconsistentPolicy |
void DDS::Publisher::set_default_library | ( | System::String^ | library_name | ) |
<<extension>> Sets the default XML library for a DDS::Publisher.
This method specifies the library that will be used as the default the next time a default library is needed during a call to one of this Publisher's operations.
Any API requiring a library_name as a parameter can use null to refer to the default library.
If the default library is not set, the DDS::Publisher inherits the default from the DDS::DomainParticipant (see DDS::DomainParticipant::set_default_library).
library_name | <<in>> Library name. If library_name is null any previous default is unset. |
One | of the Standard Return Codes |
System::String ^ DDS::Publisher::get_default_library | ( | ) |
<<extension>> Gets the default XML library associated with a DDS::Publisher.
void DDS::Publisher::set_default_profile | ( | System::String^ | library_name, |
System::String^ | profile_name | ||
) |
<<extension>> Sets the default XML profile for a DDS::Publisher.
This method specifies the profile that will be used as the default the next time a default Publisher profile is needed during a call to one of this Publisher's operations. When calling a DDS::Publisher method that requires a profile_name
parameter, you can use NULL to refer to the default profile. (This same information applies to setting a default library.)
If the default profile is not set, the DDS::Publisher inherits the default from the DDS::DomainParticipant (see DDS::DomainParticipant::set_default_profile).
This method does not set the default QoS for DDS::DataWriter objects created by the DDS::Publisher; for this functionality, use DDS::Publisher::set_default_datawriter_qos_with_profile (you may pass in NULL after having called set_default_profile()).
This method does not set the default QoS for newly created Publishers; for this functionality, use DDS::DomainParticipant::set_default_publisher_qos_with_profile.
library_name | <<in>> The library name containing the profile. |
profile_name | <<in>> The profile name. If profile_name is null any previous default is unset. |
One | of the Standard Return Codes |
System::String ^ DDS::Publisher::get_default_profile | ( | ) |
<<extension>> Gets the default XML profile associated with a DDS::Publisher.
System::String ^ DDS::Publisher::get_default_profile_library | ( | ) |
<<extension>> Gets the library where the default XML QoS profile is contained for a DDS::Publisher.
The default profile library is automatically set when DDS::Publisher::set_default_profile is called.
This library can be different than the DDS::Publisher default library (see DDS::Publisher::get_default_library).
DataWriter ^ DDS::Publisher::create_datawriter | ( | Topic^ | topic, |
DataWriterQos^ | qos, | ||
DataWriterListener^ | listener, | ||
StatusMask | mask | ||
) |
Creates a DDS::DataWriter that will be attached and belong to the DDS::Publisher.
For each application-defined type, Foo
, there is an implied, auto-generated class DDS::TypedDataWriter
that extends DDS::DataWriter and contains the operations to write data of type Foo
.
Note that a common application pattern to construct the QoS for the DDS::DataWriter is to:
When a DDS::DataWriter is created, only those transports already registered are available to the DDS::DataWriter. See Built-in Transport Plugins for details on when a builtin transport is registered.
qos
parameter, it is not safe to create the datawriter while another thread may be simultaneously calling DDS::Publisher::set_default_datawriter_qos. topic | <<in>> The DDS::Topic that the DDS::DataWriter will be associated with. Cannot be NULL. |
qos | <<in>> QoS to be used for creating the new DDS::DataWriter. The special value DDS::Publisher::DATAWRITER_QOS_DEFAULT can be used to indicate that the DDS::DataWriter should be created with the default DDS::DataWriterQos set in the DDS::Publisher. The special value DDS::Publisher.DATAWRITER_QOS_USE_TOPIC_QOS can be used to indicate that the DDS::DataWriter should be created with the combination of the default DDS::DataWriterQos set on the DDS::Publisher and the DDS::TopicQos of the DDS::Topic. Cannot be NULL. |
listener | <<in>> The listener of the DDS::DataWriter. |
mask | <<in>>. Changes of communication status to be invoked on the listener. See DDS::StatusMask. |
DataWriter ^ DDS::Publisher::create_datawriter_with_profile | ( | Topic^ | topic, |
System::String^ | library_name, | ||
System::String^ | profile_name, | ||
DataWriterListener^ | listener, | ||
StatusMask | mask | ||
) |
<<extension>> Creates a DDS::DataWriter object using the DDS::DataWriterQos associated with the input XML QoS profile.
The DDS::DataWriter will be attached and belong to the DDS::Publisher.
For each application-defined type, Foo
, there is an implied, auto-generated class DDS::TypedDataWriter
that extends DDS::DataWriter and contains the operations to write data of type Foo
.
When a DDS::DataWriter is created, only those transports already registered are available to the DDS::DataWriter. See Built-in Transport Plugins for details on when a builtin transport is registered.
topic | <<in>> The DDS::Topic that the DDS::DataWriter will be associated with. Cannot be NULL. |
library_name | <<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDS::Publisher::set_default_library). |
profile_name | <<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS::Publisher::set_default_profile). |
listener | <<in>> The listener of the DDS::DataWriter. |
mask | <<in>>. Changes of communication status to be invoked on the listener. See DDS::StatusMask. |
void DDS::Publisher::delete_datawriter | ( | DataWriter^% | a_datawriter | ) |
Deletes a DDS::DataWriter that belongs to the DDS::Publisher.
The deletion of the DDS::DataWriter will automatically unregister all instances.
a_datawriter | <<in>> The DDS::DataWriter to be deleted. |
One | of the Standard Return Codes or DDS::Retcode_PreconditionNotMet. |
DataWriter ^ DDS::Publisher::lookup_datawriter | ( | System::String^ | topic_name | ) |
Retrieves the DDS::DataWriter for a specific DDS::Topic.
This returned DDS::DataWriter is either enabled or disabled.
If more than one DDS::DataWriter is attached to the DDS::Publisher with the same topic_name
, then this operation may return any one of them.
topic_name | <<in>> Name of the DDS::Topic associated with the DDS::DataWriter that is to be looked up. Cannot be NULL. |
topic_name
. If no such DDS::DataWriter exists, this operation returns NULL. void DDS::Publisher::suspend_publications | ( | ) |
Indicates to RTI Connext that the application is about to make multiple modifications using DDS::DataWriter objects belonging to the DDS::Publisher.
It is a hint to RTI Connext so it can optimize its performance by e.g., holding the dissemination of the modifications and then batching them.
The use of this operation must be matched by a corresponding call to DDS::Publisher::resume_publications indicating that the set of modifications has completed.
If the DDS::Publisher is deleted before DDS::Publisher::resume_publications is called, any suspended updates yet to be published will be discarded.
RTI Connext is not required and does not currently make use of this hint in any way. However, similar results can be achieved by using asynchronous publishing. Combined with DDS::FlowController, ASYNCHRONOUS_PUBLISH_MODE_QOS DDS::DataWriter instances allow the user even finer control of traffic shaping and sample coalescing.
One | of the Standard Return Codes or DDS::Retcode_NotEnabled. |
void DDS::Publisher::resume_publications | ( | ) |
Indicates to RTI Connext that the application has completed the multiple changes initiated by the previous DDS::Publisher::suspend_publications.
This is a hint to RTI Connext that can be used for example, to batch all the modifications made since the DDS::Publisher::suspend_publications.
RTI Connext is not required and does not currently make use of this hint in any way. However, similar results can be achieved by using asynchronous publishing. Combined with DDS::FlowController, ASYNCHRONOUS_PUBLISH_MODE_QOS DDS::DataWriter instances allow the user even finer control of traffic shaping and sample coalescing.
One | of the Standard Return Codes or DDS::Retcode_PreconditionNotMet or DDS::Retcode_NotEnabled. |
void DDS::Publisher::begin_coherent_changes | ( | ) |
Indicates that the application will begin a coherent set of modifications using DDS::DataWriter objects attached to the DDS::Publisher.
A 'coherent set' is a set of modifications that must be propagated in such a way that they are interpreted at the receiver's 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 set are available at the receiver end.
A connectivity change may occur in the middle of a set of coherent changes; for example, the set of partitions used by the DDS::Publisher or one of its subscribers (DDS::Subscriber) may change, a late-joining DDS::DataReader may appear on the network, or a communication failure may occur. In the event that such a change prevents an entity from receiving the entire set of coherent changes, that entity must behave as if it had received none of the set.
These calls can be nested. In that case, the coherent set terminates only with the last call to DDS::Publisher::end_coherent_changes. Publisher's samples (samples published by any of the DataWriters within the Publisher) that are not published within a begin_coherent_changes/end_coherent_changes block will not be provided to the DataReaders as a set.
The support for coherent changes enables a publishing application to change the value of several data-instances that could belong to the same or different topics and have those changes be seen atomically by the readers. This is useful in cases where the values are inter-related (for example, if there are two data-instances representing the altitude and velocity vector of the same aircraft and both are changed, it may be 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).
One | of the Standard Return Codes or DDS::Retcode_NotEnabled. |
void DDS::Publisher::end_coherent_changes | ( | ) |
Terminates the coherent set initiated by the matching call to DDS::Publisher::begin_coherent_changes.
One | of the Standard Return Codes, DDS::Retcode_PreconditionNotMet or DDS::Retcode_NotEnabled. |
void DDS::Publisher::get_all_datawriters | ( | DataWriterSeq^ | writers | ) |
Retrieve all the DataWriters created from this Publisher.
One | of the Standard Return Codes |
DomainParticipant ^ DDS::Publisher::get_participant | ( | ) |
Returns the DDS::DomainParticipant to which the DDS::Publisher belongs.
Referenced by RTI.Connext.Queuing.QueueProducerParams< T >::SetEnableWaitForAck().
void DDS::Publisher::delete_contained_entities | ( | ) |
Deletes all the entities that were created by means of the "create" operation on the DDS::Publisher.
Deletes all contained DDS::DataWriter objects. Once DDS::Publisher::delete_contained_entities completes successfully, the application may delete the DDS::Publisher, knowing that it has no contained DDS::DataWriter objects.
The operation will fail with DDS::Retcode_PreconditionNotMet if any of the contained entities is in a state where it cannot be deleted.
One | of the Standard Return Codes or DDS::Retcode_PreconditionNotMet. |
void DDS::Publisher::copy_from_topic_qos | ( | DataWriterQos^ | a_datawriter_qos, |
TopicQos^ | a_topic_qos | ||
) |
Copies the policies in the DDS::TopicQos to the corresponding policies in the DDS::DataWriterQos.
Copies the policies in the DDS::TopicQos to the corresponding policies in the DDS::DataWriterQos (replacing values in the DDS::DataWriterQos, if present).
This is a "convenience" operation most useful in combination with the operations DDS::Publisher::get_default_datawriter_qos and DDS::Topic::get_qos. The operation DDS::Publisher::copy_from_topic_qos can be used to merge the DDS::DataWriter default QoS policies with the corresponding ones on the DDS::Topic. The resulting QoS can then be used to create a new DDS::DataWriter, or set its QoS.
This operation does not check the resulting DDS::DataWriterQos for consistency. This is because the 'merged' DDS::DataWriterQos may not be the final one, as the application can still modify some policies prior to applying the policies to the DDS::DataWriter.
a_datawriter_qos | <<inout>> DDS::DataWriterQos to be filled-up. Cannot be NULL. |
a_topic_qos | <<in>> DDS::TopicQos to be merged with DDS::DataWriterQos. Cannot be NULL. |
One | of the Standard Return Codes |
void DDS::Publisher::wait_for_acknowledgments | ( | Duration_t | max_wait | ) |
Blocks the calling thread until all data written by the Publisher's reliable DataWriters is acknowledged, or until timeout expires.
This operation blocks the calling thread until either all data written by the reliable DataWriters entities is acknowledged by (a) all reliable DDS::DataReader entities that are matched and alive and (b) by all required subscriptions, or until the duration specified by the max_wait
parameter elapses, whichever happens first. A successful completion indicates that all the samples written have been acknowledged; a timeout indicates that max_wait elapsed before all the data was acknowledged.
Note that if a thread is blocked in the call to this operation on a DDS::Publisher and a different thread writes new samples on any of the reliable DataWriters that belong to this Publisher, the new samples must be acknowledged before unblocking the thread that is waiting on this operation.
If none of the DDS::DataWriter instances have DDS::ReliabilityQosPolicy kind set to RELIABLE, the operation will complete successfully.
max_wait | <<in>> Specifies maximum time to wait for acknowledgements DDS::Duration_t . |
One | of the Standard Return Codes, DDS::Retcode_NotEnabled, DDS::Retcode_Timeout |
void DDS::Publisher::wait_for_asynchronous_publishing | ( | Duration_t | max_wait | ) |
<<extension>> Blocks the calling thread until asynchronous sending is complete.
This operation blocks the calling thread (up to max_wait
) until all data written by the asynchronous DDS::DataWriter entities is sent and acknowledged (if reliable) by all matched DDS::DataReader entities. A successful completion indicates that all the samples written have been sent and acknowledged where applicable; if it times out, this indicates that max_wait
elapsed before all the data was sent and/or acknowledged.
In other words, this guarantees that sending to best effort DDS::DataReader is complete in addition to what DDS::Publisher::wait_for_acknowledgments provides.
If none of the DDS::DataWriter instances have DDS::PublishModeQosPolicy::kind set to ASYNCHRONOUS_PUBLISH_MODE_QOS, the operation will complete immediately , with DDS::ReturnCode_t::RETCODE_OK.
max_wait | <<in>> Specifies maximum time to wait for acknowledgements DDS::Duration_t. |
One | of the Standard Return Codes, DDS::Retcode_NotEnabled, DDS::Retcode_Timeout |
void DDS::Publisher::set_qos | ( | PublisherQos^ | qos | ) |
Sets the publisher QoS.
This operation modifies the QoS of the DDS::Publisher.
The DDS::PublisherQos::group_data, DDS::PublisherQos::partition and DDS::PublisherQos::entity_factory can be changed. The other policies are immutable.
qos | <<in>> DDS::PublisherQos to be set to. Policies must be consistent. Immutable policies cannot be changed after DDS::Publisher is enabled. The special value DDS::DomainParticipant::PUBLISHER_QOS_DEFAULT can be used to indicate that the QoS of the DDS::Publisher should be changed to match the current default DDS::PublisherQos set in the DDS::DomainParticipant. Cannot be NULL. |
One | of the Standard Return Codes, DDS::Retcode_ImmutablePolicy, or DDS::Retcode_InconsistentPolicy. |
Referenced by RTI.Connext.Queuing.QueueProducer< TRep >::QueueProducer().
void DDS::Publisher::set_qos_with_profile | ( | System::String^ | library_name, |
System::String^ | profile_name | ||
) |
<<extension>> Change the QoS of this publisher using the input XML QoS profile.
This operation modifies the QoS of the DDS::Publisher.
The DDS::PublisherQos::group_data, DDS::PublisherQos::partition and DDS::PublisherQos::entity_factory can be changed. The other policies are immutable.
library_name | <<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDS::Publisher::set_default_library). |
profile_name | <<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS::Publisher::set_default_profile). |
One | of the Standard Return Codes, DDS::Retcode_ImmutablePolicy, or DDS::Retcode_InconsistentPolicy. |
void DDS::Publisher::get_qos | ( | PublisherQos^ | qos | ) |
Gets the publisher QoS.
This method may potentially allocate memory depending on the sequences contained in some QoS policies.
qos | <<in>> DDS::PublisherQos to be filled in. Cannot be NULL. |
One | of the Standard Return Codes |
Referenced by RTI.Connext.Queuing.QueueProducer< TRep >::QueueProducer().
void DDS::Publisher::set_listener | ( | PublisherListener^ | l, |
StatusMask | mask | ||
) |
Sets the publisher listener.
l | <<in>> DDS::PublisherListener to set to. |
mask | <<in>> DDS::StatusMask associated with the DDS::PublisherListener. |
One | of the Standard Return Codes |
PublisherListener ^ DDS::Publisher::get_listener | ( | ) |
Get the publisher listener.
|
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.
One | of the Standard Return Codes, Standard Return Codes or DDS::Retcode_PreconditionNotMet. |
Implements DDS::Entity.
|
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.
Implements DDS::Entity.
|
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.
Implements DDS::Entity.
|
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.
Implements DDS::Entity.
DataWriter ^ DDS::Publisher::lookup_datawriter_by_name | ( | String^ | datawriter_name | ) |
<<extension>> Retrieves a DDS::DataWriter contained within the DDS::Publisher the DDS::DataWriter entity name.
Every DDS::DataWriter in the system has an entity name which is configured and stored in the <<extension>> EntityName policy, ENTITY_NAME.
This operation retrieves the DDS::DataWriter within the DDS::Publisher whose name matches the one specified. If there are several DDS::DataWriter with the same name within the DDS::Publisher, the operation returns the first matching occurrence.
datawriter_name | <<in>> Entity name of the DDS::DataWriter. |