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

Inheritance diagram for DDSPublisher:

Public Member Functions
virtual DDS_ReturnCode_t	get_default_datawriter_qos (DDS_DataWriterQos &qos)=0
	Copies the default DDS_DataWriterQos values into the provided DDS_DataWriterQos instance.

virtual DDS_ReturnCode_t	set_default_datawriter_qos (const DDS_DataWriterQos &qos)=0
	Sets the default DDS_DataWriterQos values for this publisher.

virtual DDS_ReturnCode_t	set_default_datawriter_qos_with_profile (const char library_name, const char profile_name)=0
	<<eXtension>> Set the default DDS_DataWriterQos values for this publisher based on the input XML QoS profile.

virtual DDS_ReturnCode_t	set_default_library (const char *library_name)=0
	<<eXtension>> Sets the default XML library for a DDSPublisher.

virtual const char *	get_default_library ()=0
	<<eXtension>> Gets the default XML library associated with a DDSPublisher.

virtual DDS_ReturnCode_t	set_default_profile (const char library_name, const char profile_name)=0
	<<eXtension>> Sets the default XML profile for a DDSPublisher.

virtual const char *	get_default_profile ()=0
	<<eXtension>> Gets the default XML profile associated with a DDSPublisher.

virtual const char *	get_default_profile_library ()=0
	<<eXtension>> Gets the library where the default XML QoS profile is contained for a DDSPublisher.

virtual DDSDataWriter *	create_datawriter (DDSTopic topic, const DDS_DataWriterQos &qos, DDSDataWriterListener listener, DDS_StatusMask mask)=0
	Creates a DDSDataWriter that will be attached and belong to the DDSPublisher.

virtual DDSDataWriter *	create_datawriter_with_profile (DDSTopic topic, const char library_name, const char profile_name, DDSDataWriterListener listener, DDS_StatusMask mask)=0
	<<eXtension>> Creates a DDSDataWriter object using the DDS_DataWriterQos associated with the input XML QoS profile.

virtual DDS_ReturnCode_t	delete_datawriter (DDSDataWriter *a_datawriter)=0
	Deletes a DDSDataWriter that belongs to the DDSPublisher.

virtual DDSDataWriter *	lookup_datawriter (const char *topic_name)=0
	Retrieves the DDSDataWriter for a specific DDSTopic.

virtual DDS_ReturnCode_t	get_all_datawriters (DDSDataWriterSeq &writers)=0
	Retrieve all the DataWriters created from this Publisher.

virtual DDS_ReturnCode_t	suspend_publications ()=0
	Indicates to RTI Connext that the application is about to make multiple modifications using DDSDataWriter objects belonging to the DDSPublisher.

virtual DDS_ReturnCode_t	resume_publications ()=0
	Indicates to RTI Connext that the application has completed the multiple changes initiated by the previous DDSPublisher::suspend_publications.

virtual DDS_ReturnCode_t	begin_coherent_changes ()=0
	Indicates that the application will begin a coherent set of modifications using DDSDataWriter objects attached to the DDSPublisher.

virtual DDS_ReturnCode_t	end_coherent_changes ()=0
	Terminates the coherent set initiated by the matching call to DDSPublisher::begin_coherent_changes.

virtual DDSDomainParticipant *	get_participant ()=0
	Returns the DDSDomainParticipant to which the DDSPublisher belongs.

virtual DDS_ReturnCode_t	delete_contained_entities ()=0
	Deletes all the entities that were created by means of the "create" operation on the DDSPublisher.

virtual DDS_ReturnCode_t	copy_from_topic_qos (DDS_DataWriterQos &a_datawriter_qos, const DDS_TopicQos &a_topic_qos)=0
	Copies the policies in the DDS_TopicQos to the corresponding policies in the DDS_DataWriterQos.

virtual DDS_ReturnCode_t	wait_for_acknowledgments (const DDS_Duration_t &max_wait)=0
	Blocks the calling thread until all data written by the Publisher's reliable DataWriters is acknowledged, or until timeout expires.

virtual DDS_ReturnCode_t	wait_for_asynchronous_publishing (const DDS_Duration_t &max_wait)=0
	<<eXtension>> Blocks the calling thread until asynchronous sending is complete.

virtual DDS_ReturnCode_t	set_qos (const DDS_PublisherQos &qos)=0
	Sets the publisher QoS.

virtual DDS_ReturnCode_t	set_qos_with_profile (const char library_name, const char profile_name)=0
	<<eXtension>> Change the QoS of this publisher using the input XML QoS profile.

virtual DDS_ReturnCode_t	get_qos (DDS_PublisherQos &qos)=0
	Gets the publisher QoS.

virtual DDS_ReturnCode_t	set_listener (DDSPublisherListener *l, DDS_StatusMask mask=DDS_STATUS_MASK_ALL)=0
	Sets the publisher listener.

virtual DDSPublisherListener *	get_listener ()=0
	Get the publisher listener.

virtual DDSDataWriter *	lookup_datawriter_by_name_exp (const char *datawriter_name)=0
	<<experimental>> <<eXtension>> Retrieves a DDSDataWriter contained within the DDSPublisher the DDSDataWriter entity name.

Detailed Description

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

QoS:: DDS_PublisherQos

Listener:: DDSPublisherListener

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

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

See Also: Operations Allowed in Listener Callbacks

Examples:: HelloWorld_publisher.cxx.

Member Function Documentation

virtual DDS_ReturnCode_t DDSPublisher::get_default_datawriter_qos ( DDS_DataWriterQos & qos )

pure virtual

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 DDSPublisher::set_default_datawriter_qos or DDSPublisher::set_default_datawriter_qos_with_profile, or else, if the call was never made, the default values from is owning DDSDomainParticipant.

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 DDSPublisher while another thread may be simultaneously calling DDSPublisher::set_default_datawriter_qos.

Parameters

qos	<<inout>> DDS_DataWriterQos to be filled-up.

Returns: One of the Standard Return Codes

See Also: DDS_DATAWRITER_QOS_DEFAULT; DDSPublisher::create_datawriter

virtual DDS_ReturnCode_t DDSPublisher::set_default_datawriter_qos ( const DDS_DataWriterQos & qos )

pure virtual

Sets the default DDS_DataWriterQos values for this publisher.

This call causes the default values inherited from the owning DDSDomainParticipant to be overridden.

This default value will be used for newly created DDSDataWriter if DDS_DATAWRITER_QOS_DEFAULT is specified as the qos parameter when DDSPublisher::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_INCONSISTENT_POLICY

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

Parameters

qos	<<in>> Default qos to be set. The special value DDS_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 DDSPublisher::set_default_datawriter_qos had never been called.

Returns: One of the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY

virtual DDS_ReturnCode_t DDSPublisher::set_default_datawriter_qos_with_profile	(	const char *	library_name,
		const char *	profile_name
	)

pure virtual

<<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 DDSDataWriter if DDS_DATAWRITER_QOS_DEFAULT is specified as the qos parameter when DDSPublisher::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_INCONSISTENT_POLICY

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

If the input profile cannot be found, the method fails with DDS_RETCODE_ERROR.

Returns: One of the Standard Return Codes, or DDS_RETCODE_INCONSISTENT_POLICY

See Also: DDS_DATAWRITER_QOS_DEFAULT; DDSPublisher::create_datawriter_with_profile

virtual DDS_ReturnCode_t DDSPublisher::set_default_library ( const char * library_name )

pure virtual

<<eXtension>> Sets the default XML library for a DDSPublisher.

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 DDSPublisher inherits the default from the DDSDomainParticipant (see DDSDomainParticipant::set_default_library).

Parameters

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

Returns: One of the Standard Return Codes

See Also: DDSPublisher::get_default_library

virtual const char* DDSPublisher::get_default_library ( )

pure virtual

<<eXtension>> Gets the default XML library associated with a DDSPublisher.

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

See Also: DDSPublisher::set_default_library

virtual DDS_ReturnCode_t DDSPublisher::set_default_profile	(	const char *	library_name,
		const char *	profile_name
	)

pure virtual

<<eXtension>> Sets the default XML profile for a DDSPublisher.

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 DDSPublisher 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 DDSPublisher inherits the default from the DDSDomainParticipant (see DDSDomainParticipant::set_default_profile).

This method does not set the default QoS for DDSDataWriter objects created by the DDSPublisher; for this functionality, use DDSPublisher::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 DDSDomainParticipant::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.

Returns: One of the Standard Return Codes

See Also: DDSPublisher::get_default_profile; DDSPublisher::get_default_profile_library

virtual const char* DDSPublisher::get_default_profile ( )

pure virtual

<<eXtension>> Gets the default XML profile associated with a DDSPublisher.

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

See Also: DDSPublisher::set_default_profile

virtual const char* DDSPublisher::get_default_profile_library ( )

pure virtual

<<eXtension>> Gets the library where the default XML QoS profile is contained for a DDSPublisher.

The default profile library is automatically set when DDSPublisher::set_default_profile is called.

This library can be different than the DDSPublisher default library (see DDSPublisher::get_default_library).

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

See Also: DDSPublisher::set_default_profile

virtual DDSDataWriter* DDSPublisher::create_datawriter	(	DDSTopic *	topic,
		const DDS_DataWriterQos &	qos,
		DDSDataWriterListener *	listener,
		DDS_StatusMask	mask
	)

pure virtual

Creates a DDSDataWriter that will be attached and belong to the DDSPublisher.

For each application-defined type, Foo, there is an implied, auto-generated class FooDataWriter that extends DDSDataWriter and contains the operations to write data of type Foo.

Note that a common application pattern to construct the QoS for the DDSDataWriter is to:

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

When a DDSDataWriter is created, only those transports already registered are available to the DDSDataWriter. 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 DDSDataWriter will be created.; The given DDSTopic 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_DATAWRITER_QOS_DEFAULT is used for the qos parameter, it is not safe to create the datawriter while another thread may be simultaneously calling DDSPublisher::set_default_datawriter_qos.

Parameters

topic	<<in>> The DDSTopic that the DDSDataWriter will be associated with. Cannot be NULL.
qos	<<in>> QoS to be used for creating the new DDSDataWriter. The special value DDS_DATAWRITER_QOS_DEFAULT can be used to indicate that the DDSDataWriter should be created with the default DDS_DataWriterQos set in the DDSPublisher. The special value DDS_DATAWRITER_QOS_USE_TOPIC_QOS can be used to indicate that the DDSDataWriter should be created with the combination of the default DDS_DataWriterQos set on the DDSPublisher and the DDS_TopicQos of the DDSTopic.
listener	<<in>> The listener of the DDSDataWriter.
mask	<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.

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

See Also: FooDataWriter; Specifying QoS on entities for information on setting QoS before entity creation; DDS_DataWriterQos for rules on consistency among QoS; DDS_DATAWRITER_QOS_DEFAULT; DDS_DATAWRITER_QOS_USE_TOPIC_QOS; DDSPublisher::create_datawriter_with_profile; DDSPublisher::get_default_datawriter_qos; DDSTopic::set_qos; DDSPublisher::copy_from_topic_qos; DDSDataWriter::set_listener

Examples:: HelloWorld_publisher.cxx.

virtual DDSDataWriter* DDSPublisher::create_datawriter_with_profile	(	DDSTopic *	topic,
		const char *	library_name,
		const char *	profile_name,
		DDSDataWriterListener *	listener,
		DDS_StatusMask	mask
	)

pure virtual

<<eXtension>> Creates a DDSDataWriter object using the DDS_DataWriterQos associated with the input XML QoS profile.

The DDSDataWriter will be attached and belong to the DDSPublisher.

For each application-defined type, Foo, there is an implied, auto-generated class FooDataWriter that extends DDSDataWriter and contains the operations to write data of type Foo.

When a DDSDataWriter is created, only those transports already registered are available to the DDSDataWriter. 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 DDSDataWriter will be created.; The given DDSTopic 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 DDSTopic that the DDSDataWriter 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 DDSPublisher::set_default_library).
profile_name	<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSPublisher::set_default_profile).
listener	<<in>> The listener of the DDSDataWriter.
mask	<<in>>. Changes of communication status to be invoked on the listener. See DDS_StatusMask.

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

See Also: FooDataWriter; Specifying QoS on entities for information on setting QoS before entity creation; DDS_DataWriterQos for rules on consistency among QoS; DDSPublisher::create_datawriter; DDSPublisher::get_default_datawriter_qos; DDSTopic::set_qos; DDSPublisher::copy_from_topic_qos; DDSDataWriter::set_listener

virtual DDS_ReturnCode_t DDSPublisher::delete_datawriter ( DDSDataWriter * a_datawriter )

pure virtual

Deletes a DDSDataWriter that belongs to the DDSPublisher.

The deletion of the DDSDataWriter will automatically unregister all instances. Depending on the settings of the WRITER_DATA_LIFECYCLE QosPolicy, the deletion of the DDSDataWriter 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_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 DDS_BOOLEAN_FALSE.) or
Explicitly call unregister_instance_w_timestamp() for all instances modified with the *_w_timestamp() APIs before calling delete_datawriter().

Precondition: If the DDSDataWriter does not belong to the DDSPublisher, the operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.

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

Parameters

a_datawriter <<in>> The DDSDataWriter to be deleted.

Returns: One of the Standard Return Codes or DDS_RETCODE_PRECONDITION_NOT_MET.

virtual DDSDataWriter* DDSPublisher::lookup_datawriter ( const char * topic_name )

pure virtual

Retrieves the DDSDataWriter for a specific DDSTopic.

This returned DDSDataWriter is either enabled or disabled.

Parameters

topic_name <<in>> Name of the DDSTopic associated with the DDSDataWriter that is to be looked up. Cannot be NULL.

Returns: A DDSDataWriter that belongs to the DDSPublisher attached to the DDSTopic with topic_name. If no such DDSDataWriter exists, this operation returns NULL.

If more than one DDSDataWriter is attached to the DDSPublisher with the same topic_name, then this operation may return any one of them.

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

virtual DDS_ReturnCode_t DDSPublisher::get_all_datawriters ( DDSDataWriterSeq & writers )

pure virtual

Retrieve all the DataWriters created from this Publisher.

Parameters

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

Returns: One of the Standard Return Codes

virtual DDS_ReturnCode_t DDSPublisher::suspend_publications ( )

pure virtual

Indicates to RTI Connext that the application is about to make multiple modifications using DDSDataWriter objects belonging to the DDSPublisher.

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 DDSPublisher::resume_publications indicating that the set of modifications has completed.

If the DDSPublisher is deleted before DDSPublisher::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 DDSFlowController, DDS_ASYNCHRONOUS_PUBLISH_MODE_QOS DDSDataWriter instances allow the user even finer control of traffic shaping and sample coalescing.

Returns: One of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.

See Also: DDSFlowController; DDSFlowController::trigger_flow; DDS_ON_DEMAND_FLOW_CONTROLLER_NAME; DDS_PublishModeQosPolicy

virtual DDS_ReturnCode_t DDSPublisher::resume_publications ( )

pure virtual

Indicates to RTI Connext that the application has completed the multiple changes initiated by the previous DDSPublisher::suspend_publications.

This is a hint to RTI Connext that can be used for example, to batch all the modifications made since the DDSPublisher::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 DDSFlowController, DDS_ASYNCHRONOUS_PUBLISH_MODE_QOS DDSDataWriter instances allow the user even finer control of traffic shaping and sample coalescing.

Precondition: A call to DDSPublisher::resume_publications must match a previous call to DDSPublisher::suspend_publications. Otherwise the operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.

Returns: One of the Standard Return Codes or DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_NOT_ENABLED.

See Also: DDSFlowController; DDSFlowController::trigger_flow; DDS_ON_DEMAND_FLOW_CONTROLLER_NAME; DDS_PublishModeQosPolicy

virtual DDS_ReturnCode_t DDSPublisher::begin_coherent_changes ( )

pure virtual

Indicates that the application will begin a coherent set of modifications using DDSDataWriter objects attached to the DDSPublisher.

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 DDSPublisher or one of its DDSSubscriber s may change, a late-joining DDSDataReader 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 DDSPublisher::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).

Returns: One of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.

virtual DDS_ReturnCode_t DDSPublisher::end_coherent_changes ( )

pure virtual

Terminates the coherent set initiated by the matching call to DDSPublisher::begin_coherent_changes.

Precondition: If there is no matching call to DDSPublisher::begin_coherent_changes the operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET.

Returns: One of the Standard Return Codes, DDS_RETCODE_PRECONDITION_NOT_MET or DDS_RETCODE_NOT_ENABLED.

virtual DDSDomainParticipant* DDSPublisher::get_participant ( )

pure virtual

Returns the DDSDomainParticipant to which the DDSPublisher belongs.

Returns: the DDSDomainParticipant to which the DDSPublisher belongs.

virtual DDS_ReturnCode_t DDSPublisher::delete_contained_entities ( )

pure virtual

Deletes all the entities that were created by means of the "create" operation on the DDSPublisher.

Deletes all contained DDSDataWriter objects. Once DDSPublisher::delete_contained_entities completes successfully, the application may delete the DDSPublisher, knowing that it has no contained DDSDataWriter objects.

The operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET if any of the contained entities is in a state where it cannot be deleted.

Returns: One of the Standard Return Codes or DDS_RETCODE_PRECONDITION_NOT_MET.

virtual DDS_ReturnCode_t DDSPublisher::copy_from_topic_qos	(	DDS_DataWriterQos &	a_datawriter_qos,
		const DDS_TopicQos &	a_topic_qos
	)

pure virtual

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 DDSPublisher::get_default_datawriter_qos and DDSTopic::get_qos. The operation DDSPublisher::copy_from_topic_qos can be used to merge the DDSDataWriter default QoS policies with the corresponding ones on the DDSTopic. The resulting QoS can then be used to create a new DDSDataWriter, 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 DDSDataWriter.

Parameters

a_datawriter_qos	<<inout>> DDS_DataWriterQos to be filled-up.
a_topic_qos	<<in>> DDS_TopicQos to be merged with DDS_DataWriterQos.

Returns: One of the Standard Return Codes

virtual DDS_ReturnCode_t DDSPublisher::wait_for_acknowledgments ( const DDS_Duration_t & max_wait )

pure virtual

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 DDSDataReader 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 DDSPublisher 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 DDSDataWriter 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 .

Returns: One of the Standard Return Codes, DDS_RETCODE_NOT_ENABLED, DDS_RETCODE_TIMEOUT

virtual DDS_ReturnCode_t DDSPublisher::wait_for_asynchronous_publishing ( const DDS_Duration_t & max_wait )

pure virtual

<<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 DDSDataWriter entities is sent and acknowledged (if reliable) by all matched DDSDataReader 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 DDSDataReader is complete in addition to what DDSPublisher::wait_for_acknowledgments provides.

If none of the DDSDataWriter instances have DDS_PublishModeQosPolicy::kind set to DDS_ASYNCHRONOUS_PUBLISH_MODE_QOS, the operation will complete immediately, with DDS_RETCODE_OK.

Parameters

max_wait <<in>> Specifies maximum time to wait for acknowledgements DDS_Duration_t.

Returns: One of the Standard Return Codes, DDS_RETCODE_NOT_ENABLED, DDS_RETCODE_TIMEOUT

virtual DDS_ReturnCode_t DDSPublisher::set_qos ( const DDS_PublisherQos & qos )

pure virtual

Sets the publisher QoS.

This operation modifies the QoS of the DDSPublisher.

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 DDSPublisher is enabled. The special value DDS_PUBLISHER_QOS_DEFAULT can be used to indicate that the QoS of the DDSPublisher should be changed to match the current default DDS_PublisherQos set in the DDSDomainParticipant.

Returns: One of the Standard Return Codes, DDS_RETCODE_IMMUTABLE_POLICY, or DDS_RETCODE_INCONSISTENT_POLICY.

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

virtual DDS_ReturnCode_t DDSPublisher::set_qos_with_profile	(	const char *	library_name,
		const char *	profile_name
	)

pure virtual

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

This operation modifies the QoS of the DDSPublisher.

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 DDSPublisher::set_default_library).
profile_name	<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDSPublisher::set_default_profile).

Returns: One of the Standard Return Codes, DDS_RETCODE_IMMUTABLE_POLICY, or DDS_RETCODE_INCONSISTENT_POLICY.

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

virtual DDS_ReturnCode_t DDSPublisher::get_qos ( DDS_PublisherQos & qos )

pure virtual

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.

Returns: One of the Standard Return Codes

See Also: get_qos (abstract)

virtual DDS_ReturnCode_t DDSPublisher::set_listener	(	DDSPublisherListener *	l,
		DDS_StatusMask	mask = `DDS_STATUS_MASK_ALL`
	)

pure virtual

Sets the publisher listener.

Parameters

l	<<in>> DDSPublisherListener to set to.
mask	<<in>> DDS_StatusMask associated with the DDSPublisherListener.

Returns: One of the Standard Return Codes

See Also: set_listener (abstract)

virtual DDSPublisherListener* DDSPublisher::get_listener ( )

pure virtual

Get the publisher listener.

Returns: DDSPublisherListener of the DDSPublisher.

See Also: get_listener (abstract)

virtual DDSDataWriter* DDSPublisher::lookup_datawriter_by_name_exp ( const char * datawriter_name )

pure virtual

<<experimental>> <<eXtension>> Retrieves a DDSDataWriter contained within the DDSPublisher the DDSDataWriter entity name.

Every DDSDataWriter in the system has an entity name which is configured and stored in the <<eXtension>> EntityName policy, ENTITY_NAME.

This operation retrieves the DDSDataWriter within the DDSPublisher whose name matches the one specified. If there are several DDSDataWriter with the same name within the DDSPublisher, the operation returns the first matching occurrence.

Parameters

datawriter_name <<in>> Entity name of the DDSDataWriter.

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

See Also: DDSDomainParticipant::lookup_datawriter_by_name_exp

Public Member Functions

Detailed Description

Member Function Documentation

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