The DataWriter entity provides an interface for the application to publish (write) data. More...

Inheritance diagram for DDS::DataWriter:

Public Member Functions
ReturnCode_t	enable ()
	Enables the DataWriter. More...

InstanceHandle_t	get_instance_handle ()
	This operation returns the InstanceHandle_t that identifies the DataWriter.

StatusMask	get_status_changes ()
	This returns the list of triggered communication statuses in the DataWriter. More...

ReturnCode_t	set_qos (const DataWriterQos &qos)
	Sets the DataWriterQos values. More...

ReturnCode_t	get_qos (DataWriterQos &qos)
	Returns the current DataWriterQos settings held in the DataWriter dw. More...

ReturnCode_t	set_listener (DataWriterListener *a_listener, StatusMask mask)
	Installs a DataWriterListener on DataWriter dw. More...

DataWriterListener *	get_listener ()
	This operation returns the currently installed DataWriterListener. More...

class Topic *	get_topic ()
	Returns the Topic associated with DataWriter dw.

class Publisher *	get_publisher ()
	Returns the Publisher that contains DataWriter dw.

ReturnCode_t	wait_for_acknowledgments (const Duration_t &max_wait)
	Block until this writer has received acknowledgements for all written data. More...

ReturnCode_t	assert_liveliness ()
	This operation manually asserts the liveliness of the DataWriter dw. More...

InstanceHandle_t	register_instance (const void *instance_data)
	Declares the existance of an instance identified by the 'key fields' in instance_data. More...

InstanceHandle_t	register_instance_w_timestamp (const void *instance_data, const Time_t &source_timestamp)
	Declares the existance of an instance identified by the 'key fields' in instance_data. More...

ReturnCode_t	unregister_instance (const void *instance_data, const InstanceHandle_t handle)
	Indicates that the writer will no longer be providing updates the specified instance. More...

ReturnCode_t	unregister_instance_w_timestamp (const void *instance_data, const InstanceHandle_t handle, const Time_t &source_timestamp)
	Indicates that the writer will no longer be providing updates the specified instance. More...

ReturnCode_t	write (const void *instance_data, const InstanceHandle_t handle)
	Publishes the provided instance_data. More...

ReturnCode_t	write_w_timestamp (const void *instance_data, const InstanceHandle_t handle, const Time_t &source_timestamp)
	Publishes the provided instance_data. More...

ReturnCode_t	dispose (const void *instance_data, const InstanceHandle_t instance_handle)
	Indicates that the instance no longer exists. More...

ReturnCode_t	dispose_w_timestamp (const void *instance_data, const InstanceHandle_t instance_handle, const Time_t &source_timestamp)
	Indicates that the instance no longer exists. More...

ReturnCode_t	get_key_value (void *key_holder, const InstanceHandle_t handle)
	This routine will populate the data structure indicated by key_holder with the key infomation identified by handle. More...

InstanceHandle_t	lookup_instance (const void *instance_data)
	Returns the handle that identifies the data instance provided in instance_data. More...

ReturnCode_t	write_request (const void instance_data, const InstanceHandle_t h, DDS::SampleIdentity_t req_id)
	This method is used by the RPC implementation to send a request sample and record the sample identity.

ReturnCode_t	write_reply (const void instance_data, const InstanceHandle_t h, DDS::SampleIdentity_t rep_id)
	This method is used by the RPC implementation to send a reply sample populated with the related request sample identity.

ReturnCode_t	get_liveliness_lost_status (LivelinessLostStatus *status)
	Provides access to the current LivelinessLostStatus of the DataWriter. More...

ReturnCode_t	get_offered_deadline_missed_status (OfferedDeadlineMissedStatus *status)
	Provides access to the current OfferedDeadlineMissedStatus of the DataWriter. More...

ReturnCode_t	get_offered_incompatible_qos_status (OfferedIncompatibleQosStatus *status)
	Provides access to the current OfferedIncompatibleQosStatus of the DataWriter. More...

ReturnCode_t	get_publication_matched_status (PublicationMatchedStatus *status)
	Provides access to the current PublicationMatchedStatus of the DataWriter. More...

ReturnCode_t	get_matched_subscriptions (InstanceHandleSeq *subscription_handles)
	This operation retrieves the list of DataReaders currently matched with the DataWriter dw. More...

ReturnCode_t	get_matched_subscription_data (SubscriptionBuiltinTopicData *subscription_data, InstanceHandle_t &subscription_handle)
	This operation returns data that describes a particular matched DataReader identified by subscription_handle. More...

ReturnCode_t	get_guid (GUID_t *guid)
	Access the GUID which uniquely identifies this writer.

Public Member Functions inherited from DDS::Entity
virtual StatusCondition *	get_statuscondition ()
	Gets the StatusCondition associated with this Entity. NOTE: The entity maintains ownership of the statuscondition, and it remains valid only as long as the Entity is valid. Destroying the Entity also destroys the status condition.

Detailed Description

The DataWriter entity provides an interface for the application to publish (write) data.

The DataWriter is an abstract 'class' that is extended to support a particular data type required by the application. A DataReader is associated with, and writes on, a single Topic.

Member Function Documentation

ReturnCode_t DDS::DataWriter::assert_liveliness ( )

This operation manually asserts the liveliness of the DataWriter dw.

This operation is useful if the LIVELINESS QoS setting is MANUAL_BY_PARTICIPANT or MANUAL_BY_TOPIC; otherwise, it has no effect.

Note: The write operation automatically asserts livelines on the DataWriter and its DomainParticipant. Therefore, assert_liveliness is required only if hte application is not writing data frequently enough to satisfy the LIVELINESS setting.

ReturnCode_t DDS::DataWriter::dispose	(	const void *	instance_data,
		const InstanceHandle_t	instance_handle
	)

Indicates that the instance no longer exists.

If handle is not HANDLE_NIL, then handle must identify a valid instance that has been previously registered or written by this DataWriter. The current time is used as the timstamp.

ReturnCode_t DDS::DataWriter::dispose_w_timestamp	(	const void *	instance_data,
		const InstanceHandle_t	instance_handle,
		const Time_t &	source_timestamp
	)

Indicates that the instance no longer exists.

If handle is not HANDLE_NIL, then handle must identify a valid instance that has been previously registered or written by this DataWriter. The source_timestamp is used as the source timstamp for the published message.

ReturnCode_t DDS::DataWriter::enable ( )

virtual

Enables the DataWriter.

A DataWriter is created either enabled or not based on the PublisherQos setting entity_factory. When a DataWriter is not enabled, only the following sub-set of all DataWriter operations are legal:

operations to get and set QoS policies,
get_statuscondition(),
get_status_changes(),

Any other operation may return the NOT_ENABLED error. DataWriter_enable() may be called on an already enabled DataWriter [it will have no effect].

Reimplemented from DDS::Entity.

ReturnCode_t DDS::DataWriter::get_key_value	(	void *	key_holder,
		const InstanceHandle_t	handle
	)

This routine will populate the data structure indicated by key_holder with the key infomation identified by handle.

Note: This routine is data type specific. The generated type specific DataWriter includes an implementation of this routine which should be used to support type-safety.

DataWriterListener* DDS::DataWriter::get_listener ( )

This operation returns the currently installed DataWriterListener.

Note: Because the infrastructure makes a copy of the listener provided in DataWriter_set_listener(), the returned structure pointer will not match the pointer originally provided. However, the function pointers within the structure will match. Also, the application should not free the data referenced by the returned pointer.

ReturnCode_t DDS::DataWriter::get_liveliness_lost_status ( LivelinessLostStatus * status )

Provides access to the current LivelinessLostStatus of the DataWriter.

As a side-effect, this routine will reset the total_count_change status field to zero.

ReturnCode_t DDS::DataWriter::get_matched_subscription_data	(	SubscriptionBuiltinTopicData *	subscription_data,
		InstanceHandle_t &	subscription_handle
	)

This operation returns data that describes a particular matched DataReader identified by subscription_handle.

An appropriate handle can be obtained through a call to DataWriter_get_matched_subscriptions().

If subscription_handle does not identify a matched DataReader, this routine will return RETCODE_PRECONDITION_NOT_MET.

ReturnCode_t DDS::DataWriter::get_matched_subscriptions ( InstanceHandleSeq * subscription_handles )

This operation retrieves the list of DataReaders currently matched with the DataWriter dw.

This list will include the handles that identify DataReaders which have matching Topic and compatible QoS with DataWriter.

If a DataReader has been ignored by a call to DomainParticipant_ignore_subscription(), then it will not appear in the list.

ReturnCode_t DDS::DataWriter::get_offered_deadline_missed_status ( OfferedDeadlineMissedStatus * status )

Provides access to the current OfferedDeadlineMissedStatus of the DataWriter.

As a side-effect, this routine will reset the total_count_change status field to zero.

ReturnCode_t DDS::DataWriter::get_offered_incompatible_qos_status ( OfferedIncompatibleQosStatus * status )

Provides access to the current OfferedIncompatibleQosStatus of the DataWriter.

As a side-effect, this routine will reset the total_count_change status field to zero.

ReturnCode_t DDS::DataWriter::get_publication_matched_status ( PublicationMatchedStatus * status )

Provides access to the current PublicationMatchedStatus of the DataWriter.

As a side-effect, this routine will reset the total_count_change and current_count_change status fields to zero.

ReturnCode_t DDS::DataWriter::get_qos ( DataWriterQos & qos )

Returns the current DataWriterQos settings held in the DataWriter dw.

This routines copies data from the DataWriter QoS properties into qos.

Note: The qos structure may contain sequences or strings that are populated with dynamic memory. The caller is responsible for freeing the dynamic memory of these items.
For example, the sequence 'qos->user_data' may have dynamically allocated memory assigned. This can be released by a call to seq_clear(&qos->user_data).

StatusMask DDS::DataWriter::get_status_changes ( )

virtual

This returns the list of triggered communication statuses in the DataWriter.

If the DataWriter is not enabled, all statuses will be untriggered.

Implements DDS::Entity.

InstanceHandle_t DDS::DataWriter::lookup_instance ( const void * instance_data )

Returns the handle that identifies the data instance provided in instance_data.

The 'key' field values of the data are associated with a unique handle.

InstanceHandle_t DDS::DataWriter::register_instance ( const void * instance_data )

Declares the existance of an instance identified by the 'key fields' in instance_data.

The handle that uniquely identifies the instance is returned. The current time is used as the timestamp.

InstanceHandle_t DDS::DataWriter::register_instance_w_timestamp	(	const void *	instance_data,
		const Time_t &	source_timestamp
	)

Declares the existance of an instance identified by the 'key fields' in instance_data.

The handle that uniquely identifies the instance is returned. The source_timestamp is used as the timestamp.

ReturnCode_t DDS::DataWriter::set_listener	(	DataWriterListener *	a_listener,
		StatusMask	mask
	)

Installs a DataWriterListener on DataWriter dw.

Only one listener may be attached to a DataWriter at a time. A call to set_listener() will replace any current listener with a_listener.

a_listener can be NULL, which indicates a listener that does nothing.

The infrastructure will make an internal copy of the listener structure so that it need not be persisted by the application.

ReturnCode_t DDS::DataWriter::set_qos ( const DataWriterQos & qos )

Sets the DataWriterQos values.

These QoS values affect the behavior of the DataWriter.

ReturnCode_t DDS::DataWriter::unregister_instance	(	const void *	instance_data,
		const InstanceHandle_t	handle
	)

Indicates that the writer will no longer be providing updates the specified instance.

If handle is not HANDLE_NIL, then handle must identify a valid instance that has been previously registered or written by this DataWriter. The current time is used as the timstamp.

ReturnCode_t DDS::DataWriter::unregister_instance_w_timestamp	(	const void *	instance_data,
		const InstanceHandle_t	handle,
		const Time_t &	source_timestamp
	)

Indicates that the writer will no longer be providing updates the specified instance.

If handle is not HANDLE_NIL, then handle must identify a valid instance that has been previously registered or written by this DataWriter. The provided source_timestamp is used as the timstamp.

ReturnCode_t DDS::DataWriter::wait_for_acknowledgments ( const Duration_t & max_wait )

Block until this writer has received acknowledgements for all written data.

This routine will block until all data written by the writer has been acknowledged, or until the 'max_wait' duration has passed. 'max_wait' can be set to INFINITE, in which case this routine may block indefinitely.

Return values

RETCODE_TIME_OUT	returned if 'max_wait' passes before all acks are received
RETCODE_OK	returned if all acks have been received before 'max_wait'

ReturnCode_t DDS::DataWriter::write	(	const void *	instance_data,
		const InstanceHandle_t	handle
	)

Publishes the provided instance_data.

If handle is HANDLE_NIL, then the handle is determined from the 'key fields' of instance_data. The current time is used as the source timestamp for the published data. This routine may block if RELIABILITY kind == RELIABLE, RESOURCE_LIMITS are not UNLIMITED, and the local resources are exhausted. The routine will block at most 'max_blocking_time' as configured in the RELIABLITY QoS. If the routine is still unable to handle the data, after blocking, then RETCODE_TIMEOUT is returned.

The routine may return RETCODE_OUT_OF_RESOURCES if it is determined that no amount of blocking will allow the data to be processed.

On success, RETCODE_OK is returned.

ReturnCode_t DDS::DataWriter::write_w_timestamp	(	const void *	instance_data,
		const InstanceHandle_t	handle,
		const Time_t &	source_timestamp
	)

Publishes the provided instance_data.

If handle is HANDLE_NIL, then the handle is determined from the 'key fields' of instance_data. The source_timestamp is used as the source timestamp for the published data. This routine may block if RELIABILITY kind == RELIABLE, RESOURCE_LIMITS are not UNLIMITED, and the local resources are exhausted. The routine will block at most 'max_blocking_time' as configured in the RELIABLITY QoS. If the routine is still unable to handle the data, after blocking, then RETCODE_TIMEOUT is returned.

The routine may return RETCODE_OUT_OF_RESOURCES if it is determined that no amount of blocking will allow the data to be processed.

On success, RETCODE_OK is returned.

Public Member Functions

Detailed Description

Member Function Documentation