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

Inheritance diagram for Publisher:

Public Member Functions
void	get_default_datawriter_qos (DataWriterQos qos)
	Copies the default com.rti.dds.publication.DataWriterQos values into the provided com.rti.dds.publication.DataWriterQos instance.

void	set_default_datawriter_qos (DataWriterQos qos)
	Sets the default com.rti.dds.publication.DataWriterQos values for this publisher.

void	set_default_datawriter_qos_with_profile (String library_name, String profile_name)
	<<eXtension>> Set the default com.rti.dds.publication.DataWriterQos values for this publisher based on the input XML QoS profile.

DataWriter	create_datawriter (Topic topic, DataWriterQos qos, DataWriterListener listener, int mask)
	Creates a com.rti.dds.publication.DataWriter that will be attached and belong to the com.rti.dds.publication.Publisher.

DataWriter	create_datawriter_with_profile (Topic topic, String library_name, String profile_name, DataWriterListener listener, int mask)
	<<eXtension>> Creates a com.rti.dds.publication.DataWriter object using the com.rti.dds.publication.DataWriterQos associated with the input XML QoS profile.

void	delete_datawriter (DataWriter a_datawriter)
	Deletes a com.rti.dds.publication.DataWriter that belongs to the com.rti.dds.publication.Publisher.

DataWriter	lookup_datawriter (String topic_name)
	Retrieves the com.rti.dds.publication.DataWriter for a specific com.rti.dds.topic.Topic.

void	set_qos (PublisherQos qos)
	Sets the publisher QoS.

void	set_qos_with_profile (String library_name, 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.

String	get_default_library ()
	<<eXtension>> Gets the default XML library associated with a com.rti.dds.publication.Publisher.

void	set_default_library (String library_name)
	<<eXtension>> Sets the default XML library for a com.rti.dds.publication.Publisher.

String	get_default_profile ()
	<<eXtension>> Gets the default XML profile associated with a com.rti.dds.publication.Publisher.

void	set_default_profile (String library_name, String profile_name)
	<<eXtension>> Sets the default XML profile for a com.rti.dds.publication.Publisher.

String	get_default_profile_library ()
	<<eXtension>> Gets the library where the default XML QoS profile is contained for a com.rti.dds.publication.Publisher.

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

PublisherListener	get_listener ()
	Get the publisher listener.

void	suspend_publications ()
	Indicates to RTI Connext that the application is about to make multiple modifications using com.rti.dds.publication.DataWriter objects belonging to the com.rti.dds.publication.Publisher.

void	resume_publications ()
	Indicates to RTI Connext that the application has completed the multiple changes initiated by the previous com.rti.dds.publication.Publisher.suspend_publications.

void	begin_coherent_changes ()
	Indicates that the application will begin a coherent set of modifications using com.rti.dds.publication.DataWriter objects attached to the com.rti.dds.publication.Publisher.

void	end_coherent_changes ()
	Terminates the coherent set initiated by the matching call to com.rti.dds.publication.Publisher.begin_coherent_changes.

void	copy_from_topic_qos (DataWriterQos a_datawriter_qos, TopicQos a_topic_qos)
	Copies the policies in the com.rti.dds.topic.TopicQos to the corresponding policies in the com.rti.dds.publication.DataWriterQos.

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

DomainParticipant	get_participant ()
	Returns the com.rti.dds.domain.DomainParticipant to which the com.rti.dds.publication.Publisher belongs.

void	delete_contained_entities ()
	Deletes all the entities that were created by means of the "create" operation on the com.rti.dds.publication.Publisher.

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.

DataWriter	lookup_datawriter_by_name_exp (String datawriter_name)
	<<experimental>> <<eXtension>> Retrieves a com.rti.dds.publication.DataWriter contained within the com.rti.dds.publication.Publisher the com.rti.dds.publication.DataWriter entity name.

Static Public Attributes
static final DataWriterQos	DATAWRITER_QOS_DEFAULT
	Special value for creating com.rti.dds.publication.DataWriter with default QoS.

static final DataWriterQos	DATAWRITER_QOS_USE_TOPIC_QOS = new DataWriterQos()
	Special value for creating com.rti.dds.publication.DataWriter with a combination of the default com.rti.dds.publication.DataWriterQos and the com.rti.dds.topic.TopicQos.

Detailed Description

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

QoS:: com.rti.dds.publication.PublisherQos

Listener:: com.rti.dds.publication.PublisherListener

A publisher acts on the behalf of one or several com.rti.dds.publication.DataWriter objects that belong to it. When it is informed of a change to the data associated with one of its com.rti.dds.publication.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 com.rti.dds.publication.Publisher and the com.rti.dds.publication.DataWriter.

The following operations may be called even if the com.rti.dds.publication.Publisher is not enabled. Other operations will fail with the value com.rti.dds.infrastructure.RETCODE_NOT_ENABLED if called on a disabled com.rti.dds.publication.Publisher:

See Also: Operations Allowed in Listener Callbacks

Member Function Documentation

void get_default_datawriter_qos ( DataWriterQos qos )

Copies the default com.rti.dds.publication.DataWriterQos values into the provided com.rti.dds.publication.DataWriterQos instance.

The retreived qos will match the set of values specified on the last successful call to com.rti.dds.publication.Publisher.set_default_datawriter_qos or com.rti.dds.publication.Publisher.set_default_datawriter_qos_with_profile, or else, if the call was never made, the default values from is owning com.rti.dds.domain.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 com.rti.dds.publication.Publisher while another thread may be simultaneously calling com.rti.dds.publication.Publisher.set_default_datawriter_qos.

Parameters

qos	<<inout>> com.rti.dds.publication.DataWriterQos to be filled-up. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

See Also: com.rti.dds.publication.Publisher.DATAWRITER_QOS_DEFAULT; com.rti.dds.publication.Publisher.create_datawriter

void set_default_datawriter_qos ( DataWriterQos qos )

Sets the default com.rti.dds.publication.DataWriterQos values for this publisher.

This call causes the default values inherited from the owning com.rti.dds.domain.DomainParticipant to be overridden.

This default value will be used for newly created com.rti.dds.publication.DataWriter if com.rti.dds.publication.Publisher.DATAWRITER_QOS_DEFAULT is specified as the qos parameter when com.rti.dds.publication.Publisher.create_datawriter is called.

Precondition: The specified QoS policies must be consistent, or else the operation will have no effect and fail with com.rti.dds.infrastructure.RETCODE_INCONSISTENT_POLICY

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

Parameters

qos <<in>> Default qos to be set. The special value com.rti.dds.subscription.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 com.rti.dds.publication.Publisher.set_default_datawriter_qos had never been called. Cannot be NULL.

Exceptions

One	of the Standard Return Codes, or com.rti.dds.infrastructure.RETCODE_INCONSISTENT_POLICY

void set_default_datawriter_qos_with_profile	(	String	library_name,
		String	profile_name
	)

<<eXtension>> Set the default com.rti.dds.publication.DataWriterQos values for this publisher based on the input XML QoS profile.

This default value will be used for newly created com.rti.dds.publication.DataWriter if com.rti.dds.publication.Publisher.DATAWRITER_QOS_DEFAULT is specified as the qos parameter when com.rti.dds.publication.Publisher.create_datawriter is called.

Precondition: The com.rti.dds.publication.DataWriterQos contained in the specified XML QoS profile must be consistent, or else the operation will have no effect and fail with com.rti.dds.infrastructure.RETCODE_INCONSISTENT_POLICY

MT Safety:: UNSAFE. It is not safe to set the default QoS value from a com.rti.dds.publication.Publisher while another thread may be simultaneously calling com.rti.dds.publication.Publisher.set_default_datawriter_qos, com.rti.dds.publication.Publisher.get_default_datawriter_qos or calling com.rti.dds.publication.Publisher.create_datawriter with com.rti.dds.publication.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 com.rti.dds.publication.Publisher.set_default_library).
profile_name	<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see com.rti.dds.publication.Publisher.set_default_profile).

If the input profile cannot be found, the method fails with com.rti.dds.infrastructure.RETCODE_ERROR.

Exceptions

One	of the Standard Return Codes, or com.rti.dds.infrastructure.RETCODE_INCONSISTENT_POLICY

See Also: com.rti.dds.publication.Publisher.DATAWRITER_QOS_DEFAULT; com.rti.dds.publication.Publisher.create_datawriter_with_profile

DataWriter create_datawriter	(	Topic	topic,
		DataWriterQos	qos,
		DataWriterListener	listener,
		int	mask
	)

Creates a com.rti.dds.publication.DataWriter that will be attached and belong to the com.rti.dds.publication.Publisher.

For each application-defined type, com.rti.ndds.example.Foo, there is an implied, auto-generated class com.rti.ndds.example.FooDataWriter that extends com.rti.dds.publication.DataWriter and contains the operations to write data of type com.rti.ndds.example.Foo.

Note that a common application pattern to construct the QoS for the com.rti.dds.publication.DataWriter is to:

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

When a com.rti.dds.publication.DataWriter is created, only those transports already registered are available to the com.rti.dds.publication.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 com.rti.dds.publication.DataWriter will be created.; The given com.rti.dds.topic.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 com.rti.dds.publication.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 com.rti.dds.publication.Publisher.set_default_datawriter_qos.

Parameters

topic	<<in>> The com.rti.dds.topic.Topic that the com.rti.dds.publication.DataWriter will be associated with. Cannot be NULL.
qos	<<in>> QoS to be used for creating the new com.rti.dds.publication.DataWriter. The special value com.rti.dds.publication.Publisher.DATAWRITER_QOS_DEFAULT can be used to indicate that the com.rti.dds.publication.DataWriter should be created with the default com.rti.dds.publication.DataWriterQos set in the com.rti.dds.publication.Publisher. The special value com.rti.dds.publication.Publisher.DATAWRITER_QOS_USE_TOPIC_QOS can be used to indicate that the com.rti.dds.publication.DataWriter should be created with the combination of the default com.rti.dds.publication.DataWriterQos set on the com.rti.dds.publication.Publisher and the com.rti.dds.topic.TopicQos of the com.rti.dds.topic.Topic. Cannot be NULL.
listener	<<in>> The listener of the com.rti.dds.publication.DataWriter.
mask	<<in>>. Changes of communication status to be invoked on the listener. See com.rti.dds.infrastructure.StatusMask.

Returns: A com.rti.dds.publication.DataWriter of a derived class specific to the data type associated with the com.rti.dds.topic.Topic or NULL if an error occurred.

See Also: com.rti.ndds.example.FooDataWriter; Specifying QoS on entities for information on setting QoS before entity creation; com.rti.dds.publication.DataWriterQos for rules on consistency among QoS; com.rti.dds.publication.Publisher.DATAWRITER_QOS_DEFAULT; com.rti.dds.publication.Publisher.DATAWRITER_QOS_USE_TOPIC_QOS; com.rti.dds.publication.Publisher.create_datawriter_with_profile; com.rti.dds.publication.Publisher.get_default_datawriter_qos; com.rti.dds.topic.Topic.set_qos; com.rti.dds.publication.Publisher.copy_from_topic_qos; com.rti.dds.publication.DataWriter.set_listener

DataWriter create_datawriter_with_profile	(	Topic	topic,
		String	library_name,
		String	profile_name,
		DataWriterListener	listener,
		int	mask
	)

<<eXtension>> Creates a com.rti.dds.publication.DataWriter object using the com.rti.dds.publication.DataWriterQos associated with the input XML QoS profile.

The com.rti.dds.publication.DataWriter will be attached and belong to the com.rti.dds.publication.Publisher.

For each application-defined type, com.rti.ndds.example.Foo, there is an implied, auto-generated class com.rti.ndds.example.FooDataWriter that extends com.rti.dds.publication.DataWriter and contains the operations to write data of type com.rti.ndds.example.Foo.

When a com.rti.dds.publication.DataWriter is created, only those transports already registered are available to the com.rti.dds.publication.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 com.rti.dds.publication.DataWriter will be created.; The given com.rti.dds.topic.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 com.rti.dds.topic.Topic that the com.rti.dds.publication.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 com.rti.dds.publication.Publisher.set_default_library).
profile_name	<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see com.rti.dds.publication.Publisher.set_default_profile).
listener	<<in>> The listener of the com.rti.dds.publication.DataWriter.
mask	<<in>>. Changes of communication status to be invoked on the listener. See com.rti.dds.infrastructure.StatusMask.

Returns: A com.rti.dds.publication.DataWriter of a derived class specific to the data type associated with the com.rti.dds.topic.Topic or NULL if an error occurred.

See Also: com.rti.ndds.example.FooDataWriter; Specifying QoS on entities for information on setting QoS before entity creation; com.rti.dds.publication.DataWriterQos for rules on consistency among QoS; com.rti.dds.publication.Publisher.create_datawriter; com.rti.dds.publication.Publisher.get_default_datawriter_qos; com.rti.dds.topic.Topic.set_qos; com.rti.dds.publication.Publisher.copy_from_topic_qos; com.rti.dds.publication.DataWriter.set_listener

void delete_datawriter ( DataWriter a_datawriter )

Deletes a com.rti.dds.publication.DataWriter that belongs to the com.rti.dds.publication.Publisher.

The deletion of the com.rti.dds.publication.DataWriter will automatically unregister all instances. Depending on the settings of the WRITER_DATA_LIFECYCLE QosPolicy, the deletion of the com.rti.dds.publication.DataWriter may also dispose all instances.

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

If the DataWriter's com.rti.dds.infrastructure.DestinationOrderQosPolicy.kind is com.rti.dds.infrastructure.DestinationOrderQosPolicyKind.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 com.rti.dds.infrastructure.WriterDataLifecycleQosPolicy.autodispose_unregistered_instances to com.rti.dds.infrastructure.false.) or
Explicitly call unregister_instance_w_timestamp() for all instances modified with the *_w_timestamp() APIs before calling delete_datawriter().

Precondition: If the com.rti.dds.publication.DataWriter does not belong to the com.rti.dds.publication.Publisher, the operation will fail with com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET.

Postcondition: Listener installed on the com.rti.dds.publication.DataWriter will not be called after this method completes successfully.

Parameters

a_datawriter <<in>> The com.rti.dds.publication.DataWriter to be deleted.

Exceptions

One	of the Standard Return Codes or com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET.

DataWriter lookup_datawriter ( String topic_name )

Retrieves the com.rti.dds.publication.DataWriter for a specific com.rti.dds.topic.Topic.

This returned com.rti.dds.publication.DataWriter is either enabled or disabled.

Parameters

topic_name <<in>> Name of the com.rti.dds.topic.Topic associated with the com.rti.dds.publication.DataWriter that is to be looked up. Cannot be NULL.

Returns: A com.rti.dds.publication.DataWriter that belongs to the com.rti.dds.publication.Publisher attached to the com.rti.dds.topic.Topic with topic_name. If no such com.rti.dds.publication.DataWriter exists, this operation returns NULL.

If more than one com.rti.dds.publication.DataWriter is attached to the com.rti.dds.publication.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 com.rti.dds.publication.DataWriter in one thread while another thread is simultaneously creating or destroying that com.rti.dds.publication.DataWriter.

void set_qos ( PublisherQos qos )

Sets the publisher QoS.

This operation modifies the QoS of the com.rti.dds.publication.Publisher.

The com.rti.dds.publication.PublisherQos.group_data, com.rti.dds.publication.PublisherQos.partition and com.rti.dds.publication.PublisherQos.entity_factory can be changed. The other policies are immutable.

Parameters

qos <<in>> com.rti.dds.publication.PublisherQos to be set to. Policies must be consistent. Immutable policies cannot be changed after com.rti.dds.publication.Publisher is enabled. The special value com.rti.dds.domain.DomainParticipant.PUBLISHER_QOS_DEFAULT can be used to indicate that the QoS of the com.rti.dds.publication.Publisher should be changed to match the current default com.rti.dds.publication.PublisherQos set in the com.rti.dds.domain.DomainParticipant. Cannot be NULL.

Exceptions

One	of the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_IMMUTABLE_POLICY, or com.rti.dds.infrastructure.RETCODE_INCONSISTENT_POLICY.

See Also: com.rti.dds.publication.PublisherQos for rules on consistency among QoS; set_qos (abstract); Operations Allowed in Listener Callbacks

void set_qos_with_profile	(	String	library_name,
		String	profile_name
	)

<<eXtension>> Change the QoS of this publisher using the input XML QoS profile.

This operation modifies the QoS of the com.rti.dds.publication.Publisher.

The com.rti.dds.publication.PublisherQos.group_data, com.rti.dds.publication.PublisherQos.partition and com.rti.dds.publication.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 com.rti.dds.publication.Publisher.set_default_library).
profile_name	<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see com.rti.dds.publication.Publisher.set_default_profile).

Exceptions

One	of the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_IMMUTABLE_POLICY, or com.rti.dds.infrastructure.RETCODE_INCONSISTENT_POLICY.

See Also: com.rti.dds.publication.PublisherQos for rules on consistency among QoS; Operations Allowed in Listener Callbacks

void 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>> com.rti.dds.publication.PublisherQos to be filled in. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

See Also: get_qos (abstract)

String get_default_library ( )

<<eXtension>> Gets the default XML library associated with a com.rti.dds.publication.Publisher.

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

See Also: com.rti.dds.publication.Publisher.set_default_library

void set_default_library ( String library_name )

<<eXtension>> Sets the default XML library for a com.rti.dds.publication.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 com.rti.dds.publication.Publisher inherits the default from the com.rti.dds.domain.DomainParticipant (see com.rti.dds.domain.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: com.rti.dds.publication.Publisher.get_default_library

String get_default_profile ( )

<<eXtension>> Gets the default XML profile associated with a com.rti.dds.publication.Publisher.

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

See Also: com.rti.dds.publication.Publisher.set_default_profile

void set_default_profile	(	String	library_name,
		String	profile_name
	)

<<eXtension>> Sets the default XML profile for a com.rti.dds.publication.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 com.rti.dds.publication.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 com.rti.dds.publication.Publisher inherits the default from the com.rti.dds.domain.DomainParticipant (see com.rti.dds.domain.DomainParticipant.set_default_profile).

This method does not set the default QoS for com.rti.dds.publication.DataWriter objects created by the com.rti.dds.publication.Publisher; for this functionality, use com.rti.dds.publication.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 com.rti.dds.domain.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: com.rti.dds.publication.Publisher.get_default_profile; com.rti.dds.publication.Publisher.get_default_profile_library

String get_default_profile_library ( )

<<eXtension>> Gets the library where the default XML QoS profile is contained for a com.rti.dds.publication.Publisher.

The default profile library is automatically set when com.rti.dds.publication.Publisher.set_default_profile is called.

This library can be different than the com.rti.dds.publication.Publisher default library (see com.rti.dds.publication.Publisher.get_default_library).

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

See Also: com.rti.dds.publication.Publisher.set_default_profile

void set_listener	(	PublisherListener	l,
		int	mask
	)

Sets the publisher listener.

Parameters

l	<<in>> com.rti.dds.publication.PublisherListener to set to.
mask	<<in>> com.rti.dds.infrastructure.StatusMask associated with the com.rti.dds.publication.PublisherListener.

Exceptions

One	of the Standard Return Codes

See Also: set_listener (abstract)

PublisherListener get_listener ( )

Get the publisher listener.

Returns: com.rti.dds.publication.PublisherListener of the com.rti.dds.publication.Publisher.

See Also: get_listener (abstract)

void suspend_publications ( )

Indicates to RTI Connext that the application is about to make multiple modifications using com.rti.dds.publication.DataWriter objects belonging to the com.rti.dds.publication.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 com.rti.dds.publication.Publisher.resume_publications indicating that the set of modifications has completed.

If the com.rti.dds.publication.Publisher is deleted before com.rti.dds.publication.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 com.rti.dds.publication.FlowController, com.rti.dds.infrastructure.PublishModeQosPolicyKind.PublishModeQosPolicyKind.ASYNCHRONOUS_PUBLISH_MODE_QOS com.rti.dds.publication.DataWriter instances allow the user even finer control of traffic shaping and sample coalescing.

Exceptions

One	of the Standard Return Codes or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

See Also: com.rti.dds.publication.FlowController; com.rti.dds.publication.FlowController.trigger_flow; com.rti.dds.publication.FlowController.ON_DEMAND_FLOW_CONTROLLER_NAME; com.rti.dds.infrastructure.PublishModeQosPolicy

void resume_publications ( )

Indicates to RTI Connext that the application has completed the multiple changes initiated by the previous com.rti.dds.publication.Publisher.suspend_publications.

This is a hint to RTI Connext that can be used for example, to batch all the modifications made since the com.rti.dds.publication.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 com.rti.dds.publication.FlowController, com.rti.dds.infrastructure.PublishModeQosPolicyKind.PublishModeQosPolicyKind.ASYNCHRONOUS_PUBLISH_MODE_QOS com.rti.dds.publication.DataWriter instances allow the user even finer control of traffic shaping and sample coalescing.

Precondition: A call to com.rti.dds.publication.Publisher.resume_publications must match a previous call to com.rti.dds.publication.Publisher.suspend_publications. Otherwise the operation will fail with com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET.

Exceptions

One	of the Standard Return Codes or com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

See Also: com.rti.dds.publication.FlowController; com.rti.dds.publication.FlowController.trigger_flow; com.rti.dds.publication.FlowController.ON_DEMAND_FLOW_CONTROLLER_NAME; com.rti.dds.infrastructure.PublishModeQosPolicy

void begin_coherent_changes ( )

Indicates that the application will begin a coherent set of modifications using com.rti.dds.publication.DataWriter objects attached to the com.rti.dds.publication.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 com.rti.dds.publication.Publisher or one of its com.rti.dds.subscription.Subscriber s may change, a late-joining com.rti.dds.subscription.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 com.rti.dds.publication.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 com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

void end_coherent_changes ( )

Terminates the coherent set initiated by the matching call to com.rti.dds.publication.Publisher.begin_coherent_changes.

Precondition: If there is no matching call to com.rti.dds.publication.Publisher.begin_coherent_changes the operation will fail with com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET.

Exceptions

One	of the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

void copy_from_topic_qos	(	DataWriterQos	a_datawriter_qos,
		TopicQos	a_topic_qos
	)

Copies the policies in the com.rti.dds.topic.TopicQos to the corresponding policies in the com.rti.dds.publication.DataWriterQos.

Copies the policies in the com.rti.dds.topic.TopicQos to the corresponding policies in the com.rti.dds.publication.DataWriterQos (replacing values in the com.rti.dds.publication.DataWriterQos, if present).

This is a "convenience" operation most useful in combination with the operations com.rti.dds.publication.Publisher.get_default_datawriter_qos and com.rti.dds.topic.Topic.get_qos. The operation com.rti.dds.publication.Publisher.copy_from_topic_qos can be used to merge the com.rti.dds.publication.DataWriter default QoS policies with the corresponding ones on the com.rti.dds.topic.Topic. The resulting QoS can then be used to create a new com.rti.dds.publication.DataWriter, or set its QoS.

This operation does not check the resulting com.rti.dds.publication.DataWriterQos for consistency. This is because the 'merged' com.rti.dds.publication.DataWriterQos may not be the final one, as the application can still modify some policies prior to applying the policies to the com.rti.dds.publication.DataWriter.

Parameters

a_datawriter_qos	<<inout>> com.rti.dds.publication.DataWriterQos to be filled-up. Cannot be NULL.
a_topic_qos	<<in>> com.rti.dds.topic.TopicQos to be merged with com.rti.dds.publication.DataWriterQos. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

void 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 get_participant ( )

Returns the com.rti.dds.domain.DomainParticipant to which the com.rti.dds.publication.Publisher belongs.

Returns: the com.rti.dds.domain.DomainParticipant to which the com.rti.dds.publication.Publisher belongs.

void delete_contained_entities ( )

Deletes all the entities that were created by means of the "create" operation on the com.rti.dds.publication.Publisher.

Deletes all contained com.rti.dds.publication.DataWriter objects. Once com.rti.dds.publication.Publisher.delete_contained_entities completes successfully, the application may delete the com.rti.dds.publication.Publisher, knowing that it has no contained com.rti.dds.publication.DataWriter objects.

The operation will fail with com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET if any of the contained entities is in a state where it cannot be deleted.

Exceptions

One	of the Standard Return Codes or com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET.

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.

This operation blocks the calling thread until either all data written by the reliable DataWriters entities is acknowledged by (a) all reliable com.rti.dds.subscription.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 com.rti.dds.publication.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 com.rti.dds.publication.DataWriter instances have com.rti.dds.infrastructure.ReliabilityQosPolicy kind set to RELIABLE, the operation will complete successfully.

Parameters

max_wait <<in>> Specifies maximum time to wait for acknowledgements com.rti.dds.infrastructure.Duration_t .

Exceptions

One	of the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_NOT_ENABLED, com.rti.dds.infrastructure.RETCODE_TIMEOUT

void 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 com.rti.dds.publication.DataWriter entities is sent and acknowledged (if reliable) by all matched com.rti.dds.subscription.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 com.rti.dds.subscription.DataReader is complete in addition to what com.rti.dds.publication.Publisher.wait_for_acknowledgments provides.

If none of the com.rti.dds.publication.DataWriter instances have com.rti.dds.infrastructure.PublishModeQosPolicy.kind set to com.rti.dds.infrastructure.PublishModeQosPolicyKind.PublishModeQosPolicyKind.ASYNCHRONOUS_PUBLISH_MODE_QOS, the operation will complete immediately, with com.rti.dds.infrastructure.RETCODE_OK.

Parameters

max_wait <<in>> Specifies maximum time to wait for acknowledgements com.rti.dds.infrastructure.Duration_t.

Exceptions

One	of the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_NOT_ENABLED, com.rti.dds.infrastructure.RETCODE_TIMEOUT

DataWriter lookup_datawriter_by_name_exp ( String datawriter_name )

<<experimental>> <<eXtension>> Retrieves a com.rti.dds.publication.DataWriter contained within the com.rti.dds.publication.Publisher the com.rti.dds.publication.DataWriter entity name.

Every com.rti.dds.publication.DataWriter in the system has an entity name which is configured and stored in the <<eXtension>> EntityName policy, ENTITY_NAME.

This operation retrieves the com.rti.dds.publication.DataWriter within the com.rti.dds.publication.Publisher whose name matches the one specified. If there are several com.rti.dds.publication.DataWriter with the same name within the com.rti.dds.publication.Publisher, the operation returns the first matching occurrence.

Parameters

datawriter_name <<in>> Entity name of the com.rti.dds.publication.DataWriter.

Returns: The first com.rti.dds.publication.DataWriter found with the specified name or NULL if it is not found.

See Also: com.rti.dds.domain.DomainParticipant.lookup_datawriter_by_name_exp

Public Member Functions

Static Public Attributes

Detailed Description

Member Function Documentation

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