<<interface>> A publisher is the object responsible for the actual dissemination of publications. More...

#include <managed_publication.h>

Inheritance diagram for DDS::Publisher:

Public Member Functions
void	get_default_datawriter_qos (DataWriterQos^ qos)
	Copies the default DDS::DataWriterQos values into the provided DDS::DataWriterQos instance.

void	set_default_datawriter_qos (DataWriterQos^ qos)
	Sets the default DDS::DataWriterQos values for this publisher.

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.

void	set_default_library (System::String^ library_name)
	<<eXtension>> Sets the default XML library for a DDS::Publisher.

System::String^	get_default_library ()
	<<eXtension>> Gets the default XML library associated with a DDS::Publisher.

void	set_default_profile (System::String^ library_name, System::String^ profile_name)
	<<eXtension>> Sets the default XML profile for a DDS::Publisher.

System::String^	get_default_profile ()
	<<eXtension>> Gets the default XML profile associated with a DDS::Publisher.

System::String^	get_default_profile_library ()
	<<eXtension>> Gets the library where the default XML QoS profile is contained for a DDS::Publisher.

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.

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.

void	delete_datawriter (DataWriter^ %a_datawriter)
	Deletes a DDS::DataWriter that belongs to the DDS::Publisher.

DataWriter^	lookup_datawriter (System::String^ topic_name)
	Retrieves the DDS::DataWriter for a specific DDS::Topic.

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.

void	resume_publications ()
	Indicates to RTI Connext that the application has completed the multiple changes initiated by the previous DDS::Publisher::suspend_publications.

void	begin_coherent_changes ()
	Indicates that the application will begin a coherent set of modifications using DDS::DataWriter objects attached to the DDS::Publisher.

void	end_coherent_changes ()
	Terminates the coherent set initiated by the matching call to DDS::Publisher::begin_coherent_changes.

void	get_all_datawriters (DataWriterSeq^ writers)
	Retrieve all the DataWriters created from this Publisher.

DomainParticipant^	get_participant ()
	Returns the DDS::DomainParticipant to which the DDS::Publisher belongs.

void	delete_contained_entities ()
	Deletes all the entities that were created by means of the "create" operation on the DDS::Publisher.

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.

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.

void	wait_for_asynchronous_publishing (Duration_t max_wait)
	<<eXtension>> Blocks the calling thread until asynchronous sending is complete.

void	set_qos (PublisherQos^ qos)
	Sets the publisher QoS.

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.

void	get_qos (PublisherQos^ qos)
	Gets the publisher QoS.

void	set_listener (PublisherListener^ l, StatusMask mask)
	Sets the publisher listener.

PublisherListener^	get_listener ()
	Get the publisher listener.

virtual void	enable () override
	Enables the DDS::Entity.

virtual StatusCondition^	get_statuscondition () override
	Allows access to the DDS::StatusCondition associated with the DDS::Entity.

virtual StatusMask	get_status_changes () override
	Retrieves the list of communication statuses in the DDS::Entity that are triggered.

virtual InstanceHandle_t	get_instance_handle () override
	Allows access to the DDS::InstanceHandle_t associated with the DDS::Entity.

DataWriter^	lookup_datawriter_by_name_exp (String^ datawriter_name)
	<<experimental>> <<eXtension>> Retrieves a DDS::DataWriter contained within the DDS::Publisher the DDS::DataWriter entity name.

Properties
static DataWriterQos^	DATAWRITER_QOS_DEFAULT `[get]`
	Special value for creating DDS::DataWriter with default QoS.

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.

Detailed Description

<<interface>> A publisher is the object responsible for the actual dissemination of publications.

QoS:: DDS::PublisherQos

Listener:: DDS::PublisherListener

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:

See Also: Operations Allowed in Listener Callbacks

Examples:: HelloWorld_publisher.cpp.

Member Function Documentation

void DDS::Publisher::get_default_datawriter_qos ( DataWriterQos^ qos )

Copies the default DDS::DataWriterQos values into the provided DDS::DataWriterQos instance.

The retreived 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 is owning DDS::DomainParticipant.

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

MT Safety:: UNSAFE. It is not safe to retrieve the default QoS value from a DDS::Publisher while another thread may be simultaneously calling DDS::Publisher::set_default_datawriter_qos.

Parameters

qos	<<inout>> DDS::DataWriterQos to be filled-up. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

See Also: DDS::Publisher::DATAWRITER_QOS_DEFAULT; DDS::Publisher::create_datawriter

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.

Precondition: The specified QoS policies must be consistent, or else the operation will have no effect and fail with DDS::Retcode_InconsistentPolicy

MT Safety:: UNSAFE. It is not safe to set the default QoS value from a DDS::Publisher while another thread may be simultaneously calling DDS::Publisher::set_default_datawriter_qos, DDS::Publisher::get_default_datawriter_qos or calling DDS::Publisher::create_datawriter with DDS::Publisher::DATAWRITER_QOS_DEFAULT as the qos parameter.

Parameters

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.

Exceptions

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.

Precondition: The DDS::DataWriterQos contained in the specified XML QoS profile must be consistent, or else the operation will have no effect and fail with DDS::Retcode_InconsistentPolicy

MT Safety:: UNSAFE. It is not safe to set the default QoS value from a DDS::Publisher while another thread may be simultaneously calling DDS::Publisher::set_default_datawriter_qos, DDS::Publisher::get_default_datawriter_qos or calling DDS::Publisher::create_datawriter with DDS::Publisher::DATAWRITER_QOS_DEFAULT as the qos parameter.

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::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.

Exceptions

One	of the Standard Return Codes, or DDS::Retcode_InconsistentPolicy

See Also: DDS::Publisher::DATAWRITER_QOS_DEFAULT; DDS::Publisher::create_datawriter_with_profile

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).

Parameters

library_name <<in>> Library name. If library_name is null any previous default is unset.

Exceptions

One	of the Standard Return Codes

See Also: DDS::Publisher::get_default_library

System::String ^ DDS::Publisher::get_default_library ( )

<<eXtension>> Gets the default XML library associated with a DDS::Publisher.

Returns: The default library or null if the default library was not set.

See Also: DDS::Publisher::set_default_library

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.

Parameters

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.

Exceptions

One	of the Standard Return Codes

See Also: DDS::Publisher::get_default_profile; DDS::Publisher::get_default_profile_library

System::String ^ DDS::Publisher::get_default_profile ( )

<<eXtension>> Gets the default XML profile associated with a DDS::Publisher.

Returns: The default profile or null if the default profile was not set.

See Also: DDS::Publisher::set_default_profile

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).

Returns: The default profile library or null if the default profile was not set.

See Also: DDS::Publisher::set_default_profile

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:

Retrieve the QoS policies on the associated DDS::Topic by means of the DDS::Topic::get_qos operation.
Retrieve the default DDS::DataWriter qos by means of the DDS::Publisher::get_default_datawriter_qos operation.
Combine those two QoS policies (for example, using DDS::Publisher::copy_from_topic_qos) and selectively modify policies as desired.

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.

Precondition: If publisher is enabled, topic must have been enabled. Otherwise, this operation will fail and no DDS::DataWriter will be created.; The given DDS::Topic must have been created from the same participant as this publisher. If it was created from a different participant, this method will fail.

MT Safety:: UNSAFE. If DDS::Publisher::DATAWRITER_QOS_DEFAULT is used for the qos parameter, it is not safe to create the datawriter while another thread may be simultaneously calling DDS::Publisher::set_default_datawriter_qos.

Parameters

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::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.

Returns: A DDS::DataWriter of a derived class specific to the data type associated with the DDS::Topic or NULL if an error occurred.

See Also: DDS::TypedDataWriter; Specifying QoS on entities for information on setting QoS before entity creation; DDS::DataWriterQos for rules on consistency among QoS; DDS::Publisher::DATAWRITER_QOS_DEFAULT; ::DDS::DATAWRITER_QOS_USE_TOPIC_QOS; DDS::Publisher::create_datawriter_with_profile; DDS::Publisher::get_default_datawriter_qos; DDS::Topic::set_qos; DDS::Publisher::copy_from_topic_qos; DDS::DataWriter::set_listener

Examples:: HelloWorld_publisher.cpp.

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.

Precondition: If publisher is enabled, topic must have been enabled. Otherwise, this operation will fail and no DDS::DataWriter will be created.; The given DDS::Topic must have been created from the same participant as this publisher. If it was created from a different participant, this method will return NULL.

Parameters

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.

Returns: A DDS::DataWriter of a derived class specific to the data type associated with the DDS::Topic or NULL if an error occurred.

See Also: DDS::TypedDataWriter; Specifying QoS on entities for information on setting QoS before entity creation; DDS::DataWriterQos for rules on consistency among QoS; DDS::Publisher::create_datawriter; DDS::Publisher::get_default_datawriter_qos; DDS::Topic::set_qos; DDS::Publisher::copy_from_topic_qos; DDS::DataWriter::set_listener

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. Depending on the settings of the WRITER_DATA_LIFECYCLE QosPolicy, the deletion of the DDS::DataWriter may also dispose all instances.

Special Instructions if Using 'Timestamp' APIs and BY_SOURCE_TIMESTAMP Destination Ordering:

If the DataWriter's DDS::DestinationOrderQosPolicy::kind is ::DDS::DestinationOrderQosPolicyKind::BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS, calls to delete_datawriter() may fail if your application has previously used the 'with timestamp' APIs (write_w_timestamp(), register_instance_w_timestamp(), unregister_instance_w_timestamp(), or dispose_w_timestamp()) with a timestamp larger (later) than the time at which delete_datawriter() is called. To prevent delete_datawriter() from failing in this situation, either:

Change the WRITER_DATA_LIFECYCLE QosPolicy so that RTI Connext will not autodispose unregistered instances (set DDS::WriterDataLifecycleQosPolicy::autodispose_unregistered_instances to false.) or
Explicitly call unregister_instance_w_timestamp() for all instances modified with the *_w_timestamp() APIs before calling delete_datawriter().

Precondition: If the DDS::DataWriter does not belong to the DDS::Publisher, the operation will fail with DDS::Retcode_PreconditionNotMet.

Postcondition: Listener installed on the DDS::DataWriter will not be called after this method completes successfully.

Parameters

a_datawriter <<in>> The DDS::DataWriter to be deleted.

Exceptions

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.

Parameters

topic_name <<in>> Name of the DDS::Topic associated with the DDS::DataWriter that is to be looked up. Cannot be NULL.

Returns: A DDS::DataWriter that belongs to the DDS::Publisher attached to the DDS::Topic with topic_name. If no such DDS::DataWriter exists, this operation returns NULL.

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.

MT Safety:: UNSAFE. It is not safe to lookup a DDS::DataWriter in one thread while another thread is simultaneously creating or destroying that DDS::DataWriter.

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, ::DDS::PublishModeQosPolicyKind::ASYNCHRONOUS_PUBLISH_MODE_QOS DDS::DataWriter instances allow the user even finer control of traffic shaping and sample coalescing.

Exceptions

One	of the Standard Return Codes or DDS::Retcode_NotEnabled.

See Also: DDS::FlowController; DDS::FlowController::trigger_flow; ::DDS::ON_DEMAND_FLOW_CONTROLLER_NAME; DDS::PublishModeQosPolicy

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, ::DDS::PublishModeQosPolicyKind::ASYNCHRONOUS_PUBLISH_MODE_QOS DDS::DataWriter instances allow the user even finer control of traffic shaping and sample coalescing.

Precondition: A call to DDS::Publisher::resume_publications must match a previous call to DDS::Publisher::suspend_publications. Otherwise the operation will fail with DDS::Retcode_PreconditionNotMet.

Exceptions

One	of the Standard Return Codes or DDS::Retcode_PreconditionNotMet or DDS::Retcode_NotEnabled.

See Also: DDS::FlowController; DDS::FlowController::trigger_flow; ::DDS::ON_DEMAND_FLOW_CONTROLLER_NAME; DDS::PublishModeQosPolicy

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 DDS::Subscriber s 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.

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).

Exceptions

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.

Precondition: If there is no matching call to DDS::Publisher::begin_coherent_changes the operation will fail with DDS::Retcode_PreconditionNotMet.

Exceptions

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.

Parameters

writers <<inout>> Sequence where the DataWriters will be added

Exceptions

One	of the Standard Return Codes

DomainParticipant ^ DDS::Publisher::get_participant ( )

Returns the DDS::DomainParticipant to which the DDS::Publisher belongs.

Returns: the DDS::DomainParticipant to which the DDS::Publisher belongs.

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.

Exceptions

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.

Parameters

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.

Exceptions

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 return value of 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.

Parameters

max_wait <<in>> Specifies maximum time to wait for acknowledgements DDS::Duration_t .

Exceptions

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 ::DDS::PublishModeQosPolicyKind::ASYNCHRONOUS_PUBLISH_MODE_QOS, the operation will complete immediately, with ::DDS::Exception::RETCODE_OK.

Parameters

max_wait <<in>> Specifies maximum time to wait for acknowledgements DDS::Duration_t.

Exceptions

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.

Parameters

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.

Exceptions

One	of the Standard Return Codes, DDS::Retcode_ImmutablePolicy, or DDS::Retcode_InconsistentPolicy.

See Also: DDS::PublisherQos for rules on consistency among QoS; set_qos (abstract); Operations Allowed in Listener Callbacks

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.

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::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).

Exceptions

One	of the Standard Return Codes, DDS::Retcode_ImmutablePolicy, or DDS::Retcode_InconsistentPolicy.

See Also: DDS::PublisherQos for rules on consistency among QoS; Operations Allowed in Listener Callbacks

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.

Parameters

qos	<<in>> DDS::PublisherQos to be filled in. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

See Also: get_qos (abstract)

void DDS::Publisher::set_listener	(	PublisherListener^	l,
		StatusMask	mask
	)

Sets the publisher listener.

Parameters

l	<<in>> DDS::PublisherListener to set to.
mask	<<in>> ::DDS::StatusMask associated with the DDS::PublisherListener.

Exceptions

One	of the Standard Return Codes

See Also: set_listener (abstract)

PublisherListener ^ DDS::Publisher::get_listener ( )

Get the publisher listener.

Returns: DDS::PublisherListener of the DDS::Publisher.

See Also: get_listener (abstract)

virtual void DDS::Publisher::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:

set or get the QoS policies (including default QoS policies) and listener
DDS::Entity::get_statuscondition
'factory' operations
DDS::Entity::get_status_changes and other get status operations (although the status of a disabled entity never changes)
'lookup' operations

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 that is disabled are created disabled, regardless of the setting of the DDS::EntityFactoryQosPolicy.

Calling enable on an Entity whose factory 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.

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

One	of the Standard Return Codes, Standard Return Codes or DDS::Retcode_PreconditionNotMet.

Implements DDS::Entity.

virtual StatusCondition ^ DDS::Publisher::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.

virtual StatusMask DDS::Publisher::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.

virtual InstanceHandle_t DDS::Publisher::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.

DataWriter ^ DDS::Publisher::lookup_datawriter_by_name_exp ( String^ datawriter_name )

<<experimental>> <<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.

Parameters

datawriter_name <<in>> Entity name of the DDS::DataWriter.

Returns: The first DDS::DataWriter found with the specified name or NULL if it is not found.

See Also: DDS::DomainParticipant::lookup_datawriter_by_name_exp

Public Member Functions

Properties

Detailed Description

Member Function Documentation

Special Instructions if Using 'Timestamp' APIs and BY_SOURCE_TIMESTAMP Destination Ordering: