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

#include <dds_cpp_publication.hxx>

Inheritance diagram for DDSPublisher:

Public Member Functions
virtual DDSDataWriter *	create_datawriter (DDSTopic topic, const DDS_DataWriterQos &qos, DDSDataWriterListener listener, DDS_StatusMask mask)=0
	<<cert>> Creates a DDSDataWriter that will be attached and belong to the DDSPublisher.
virtual DDS_ReturnCode_t	delete_datawriter (DDSDataWriter *a_datawriter)=0
	Deletes a DDSDataWriter that belongs to the DDSPublisher.
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 DDSDataWriter *	lookup_datawriter (const char *topic_name)=0
	<<cert>> Retrieves the DDSDataWriter for a specific DDSTopic.
virtual DDSDataWriter *	lookup_datawriter_by_name (const char *writer_name)=0
	<<cert>> Retrieves a DDSDataWriter by its entity name within this DDSPublisher
virtual DDSDomainParticipant *	get_participant ()=0
	<<cert>> Returns the DDSDomainParticipant to which the DDSPublisher belongs.
virtual DDS_ReturnCode_t	get_qos (DDS_PublisherQos &qos)=0
	Gets the publisher QoS.
virtual DDS_ReturnCode_t	set_qos (const DDS_PublisherQos &qos)=0
	Sets the publisher QoS.
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	set_listener (const DDSPublisherListener *listener, DDS_StatusMask mask)=0
	Sets the publisher listener.
virtual DDSPublisherListener *	get_listener ()=0
	Get the publisher listener.
Public Member Functions inherited from DDSEntity
DDS_ReturnCode_t	enable ()
	<<cert>> Enables the DDSEntity.
DDSStatusCondition *	get_statuscondition ()
	<<cert>> Return the DDSStatusCondition associated with a particular DDSEntity.
DDS_StatusMask	get_status_changes ()
	<<cert>> Retrieves the list of communication statuses in the DDSEntity that are triggered.
DDS_InstanceHandle_t	get_instance_handle ()
	<<cert>> Allows access to the DDS_InstanceHandle_t associated with the DDSEntity.

Detailed Description

<<interface>> <<cert>> 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:

The base-class operations DDSEntity::enable
DDSPublisher::create_datawriter, DDSPublisher::delete_datawriter, DDSPublisher::delete_contained_entities,

Member Function Documentation

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

pure virtual

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

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.

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.

Parameters:

listener	<<in>> The listener of the DDSDataWriter.
mask	<<in>>. Changes of communication status to be invoked on the listener.

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

See also:: Specifying QoS on entities for information on setting QoS before entity creation; DDS_DataWriterQos for rules on consistency among QoS; DDS_DATAWRITER_QOS_DEFAULT

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.

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 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 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::get_default_datawriter_qos or calling DDSPublisher::create_datawriter with DDS_DATAWRITER_QOS_DEFAULT as the qos parameter.

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 retrieve the default QoS value from a DDSPublisher while another thread may be simultaneously calling 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 have used if DDSPublisher::set_default_datawriter_qos had never been called.

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

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

pure virtual

<<cert>> 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 DDSDataWriter* DDSPublisher::lookup_datawriter_by_name ( const char * writer_name )

pure virtual

<<cert>> Retrieves a DDSDataWriter by its entity name within this DDSPublisher

This returned DDSDataWriter is either enabled or disabled.

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

This operation retrieves a DDSDataWriter within the DDSPublisher given the entity's name. If there are several DDSDataWriter with the same name within the DDSPublisher, this function returns the first matching occurrence.

Parameters:

writer_name <<in>> Entity name of the DDSDataWriter. Cannot be NULL.

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

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 DDSDomainParticipant* DDSPublisher::get_participant ( )

pure virtual

<<cert>> Returns the DDSDomainParticipant to which the DDSPublisher belongs.

Returns:: the DDSDomainParticipant to which the DDSPublisher belongs.

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_qos ( const DDS_PublisherQos & qos )

pure virtual

Sets the publisher QoS.

This operation modifies the QoS of the DDSPublisher.

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

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::set_listener	(	const DDSPublisherListener *	listener,
		DDS_StatusMask	mask
	)

pure virtual

Sets the publisher listener.

Parameters:

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

Public Member Functions

Detailed Description

Member Function Documentation