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

Related Functions
(Note that these are not member functions.)
DDS_ReturnCode_t	DDS_DataWriter_enable (DDS_DataWriter dw)
	Enables the DDS_DataWriter. More...

DDS_InstanceHandle_t	DDS_DataWriter_get_instance_handle (DDS_DataWriter dw)
	This operation returns the InstanceHandle_t that identifies the DataWriter.

DDS_StatusCondition	DDS_DataWriter_get_statuscondition (DDS_DataWriter dw)
	This operation allows access to the DDS_StatusCondition associated with the DataWriter. More...

DDS_StatusMask	DDS_DataWriter_get_status_changes (DDS_DataWriter dw)
	This returns the list of triggered communication statuses in the DataWriter. More...

DDS_ReturnCode_t	DDS_DataWriter_set_qos (DDS_DataWriter dw, const DDS_DataWriterQos *qos)
	Sets the DDS_DataWriterQos values. More...

DDS_ReturnCode_t	DDS_DataWriter_get_qos (DDS_DataWriter dw, DDS_DataWriterQos *qos)
	Returns the current DDS_DataWriterQos settings held in the DataWriter dw. More...

DDS_ReturnCode_t	DDS_DataWriter_set_listener (DDS_DataWriter dw, DDS_DataWriterListener *a_listener, DDS_StatusMask mask)
	Installs a DDS_DataWriterListener on DataWriter dw. More...

DDS_ReturnCode_t	DDS_DataWriter_set_listener_cd (DDS_DataWriter dw, DDS_DataWriterListener_cd a_listener, DDS_StatusMask mask, void callback_data)
	Installs a DDS_DataWriterListener_cd on DataWriter dw. More...

DDS_DataWriterListener *	DDS_DataWriter_get_listener (DDS_DataWriter dw)
	This operation returns the currently installed DDS_DataWriterListener. More...

DDS_DataWriterListener_cd *	DDS_DataWriter_get_listener_cd (DDS_DataWriter dw)
	This operation returns the currently installed DDS_DataWriterListener_cd. More...

DDS_ReturnCode_t	DDS_DataWriter_wait_for_acknowledgments (DDS_DataWriter dw, const DDS_Duration_t *max_wait)
	Block until this writer has received acknowledgements for all written data. More...

DDS_Topic	DDS_DataWriter_get_topic (DDS_DataWriter dw)
	Returns the DDS_Topic associated with DataWriter dw.

DDS_Publisher	DDS_DataWriter_get_publisher (DDS_DataWriter dw)
	Returns the DDS_Publisher that contains DataWriter dw.

DDS_ReturnCode_t	DDS_DataWriter_assert_liveliness (DDS_DataWriter dw)
	This operation manually asserts the liveliness of the DataWriter dw. More...

DDS_ReturnCode_t	DDS_DataWriter_get_matched_subscriptions (DDS_DataWriter dw, DDS_InstanceHandleSeq *subscription_handles)
	This operation retrieves the list of DataReaders currently matched with the DataWriter dw. More...

DDS_ReturnCode_t	DDS_DataWriter_get_matched_subscription_data (DDS_DataWriter dw, DDS_SubscriptionBuiltinTopicData *subscription_data, const DDS_InstanceHandle_t subscription_handle)
	This operation returns data that describes a particular matched DataReader identified by subscription_handle. More...

DDS_ReturnCode_t	DDS_DataWriter_get_liveliness_lost_status (DDS_DataWriter dw, DDS_LivelinessLostStatus *status)
	Provides access to the current DDS_LivelinessLostStatus of the DataWriter. More...

DDS_ReturnCode_t	DDS_DataWriter_get_offered_deadline_missed_status (DDS_DataWriter dw, DDS_OfferedDeadlineMissedStatus *status)
	Provides access to the current DDS_OfferedDeadlineMissedStatus of the DataWriter. More...

DDS_ReturnCode_t	DDS_DataWriter_get_offered_incompatible_qos_status (DDS_DataWriter dw, DDS_OfferedIncompatibleQosStatus *status)
	Provides access to the current DDS_OfferedIncompatibleQosStatus of the DataWriter. More...

DDS_ReturnCode_t	DDS_DataWriter_get_publication_matched_status (DDS_DataWriter dw, DDS_PublicationMatchedStatus *status)
	Provides access to the current DDS_PublicationMatchedStatus of the DataWriter. More...

DDS_ReturnCode_t	DDS_DataWriter_get_cache_stats (DDS_DataWriter dw, DDS_CacheStatistics *stats)
	Provides access to the current cache statistics of the DataWriter. More...

DDS_ReturnCode_t	DDS_DataWriter_get_guid (DDS_DataWriter dw, DDS_GUID_t *guid)
	Access the GUID which uniquely identifies this writer.

DDS_ReturnCode_t	DDS_DataWriter_get_key_value (DDS_DataWriter dw, void *key_holder, const DDS_InstanceHandle_t handle)
	This routine will populate the data structure indicated by key_holder with the key infomation identified by handle. More...

DDS_InstanceHandle_t	DDS_DataWriter_lookup_instance (DDS_DataWriter dw, const void *instance_data)
	Returns the handle that identifies the data instance provided in instance_data. More...

DDS_InstanceHandle_t	DDS_DataWriter_register_instance (DDS_DataWriter dw, const void *instance_data)
	Declares the existance of an instance identified by the 'key fields' in instance_data. More...

DDS_InstanceHandle_t	DDS_DataWriter_register_instance_w_timestamp (DDS_DataWriter dw, const void *instance_data, const DDS_Time_t source_timestamp)
	Declares the existance of an instance identified by the 'key fields' in instance_data. More...

DDS_ReturnCode_t	DDS_DataWriter_unregister_instance (DDS_DataWriter dw, const void *instance_data, const DDS_InstanceHandle_t handle)
	Indicates that the writer will no longer be providing updates the specified instance. More...

DDS_ReturnCode_t	DDS_DataWriter_unregister_instance_w_timestamp (DDS_DataWriter dw, const void *instance_data, DDS_InstanceHandle_t handle, const DDS_Time_t source_timestamp)
	Indicates that the writer will no longer be providing updates the specified instance. More...

DDS_ReturnCode_t	DDS_DataWriter_write (DDS_DataWriter dw, const void *instance_data, const DDS_InstanceHandle_t handle)
	Publishes the provided instance_data. More...

DDS_ReturnCode_t	DDS_DataWriter_write_w_timestamp (DDS_DataWriter dw, const void *instance_data, const DDS_InstanceHandle_t handle, const DDS_Time_t source_timestamp)
	Publishes the provided instance_data. More...

DDS_ReturnCode_t	DDS_DataWriter_dispose (DDS_DataWriter dw, const void *instance_data, const DDS_InstanceHandle_t instance_handle)
	Indicates that the instance no longer exists. More...

DDS_ReturnCode_t	DDS_DataWriter_dispose_w_timestamp (DDS_DataWriter dw, const void *instance_data, const DDS_InstanceHandle_t instance_handle, const DDS_Time_t source_timestamp)
	Indicates that the instance no longer exists. More...

Detailed Description

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

Friends And Related Function Documentation

DDS_ReturnCode_t DDS_DataWriter_assert_liveliness ( DDS_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.

DDS_ReturnCode_t DDS_DataWriter_dispose	(	DDS_DataWriter	dw,
		const void *	instance_data,
		const DDS_InstanceHandle_t	instance_handle
	)

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.

DDS_ReturnCode_t DDS_DataWriter_dispose_w_timestamp	(	DDS_DataWriter	dw,
		const void *	instance_data,
		const DDS_InstanceHandle_t	instance_handle,
		const DDS_Time_t	source_timestamp
	)

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.

DDS_ReturnCode_t DDS_DataWriter_enable ( DDS_DataWriter dw )

A DataWriter is created either enabled or not based on the DDS_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 DDS_NOT_ENABLED error. DDS_DataWriter_enable() may be called on an already enabled DataWriter [it will have no effect].

DDS_ReturnCode_t DDS_DataWriter_get_cache_stats	(	DDS_DataWriter	dw,
		DDS_CacheStatistics *	stats
	)

This routine will populate 'stats' with the current statistics.

DDS_ReturnCode_t DDS_DataWriter_get_key_value	(	DDS_DataWriter	dw,
		void *	key_holder,
		const DDS_InstanceHandle_t	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.

DDS_DataWriterListener * DDS_DataWriter_get_listener ( DDS_DataWriter dw )

Note: Because the infrastructure makes a copy of the listener provided in DDS_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.

DDS_DataWriterListener_cd * DDS_DataWriter_get_listener_cd ( DDS_DataWriter dw )

Note: Because the infrastructure holds a pointer to the listener provided in DDS_DataWriter_set_listener_cd(), the returned structure pointer will match the pointer originally provided. The application should not free the data referenced by the returned pointer.

DDS_ReturnCode_t DDS_DataWriter_get_liveliness_lost_status	(	DDS_DataWriter	dw,
		DDS_LivelinessLostStatus *	status
	)

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

DDS_ReturnCode_t DDS_DataWriter_get_matched_subscription_data	(	DDS_DataWriter	dw,
		DDS_SubscriptionBuiltinTopicData *	subscription_data,
		const DDS_InstanceHandle_t	subscription_handle
	)

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

If subscription_handle does not identify a matched DataReader, this routine will return DDS_RETCODE_PRECONDITION_NOT_MET. To reclaim any memory returned in the 'subscription_data' parameter, call DDS_DCPSSubscription_clear(subscription_data).

DDS_ReturnCode_t DDS_DataWriter_get_matched_subscriptions	(	DDS_DataWriter	dw,
		DDS_InstanceHandleSeq *	subscription_handles
	)

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 DDS_DomainParticipant_ignore_subscription(), then it will not appear in the list.

DDS_ReturnCode_t DDS_DataWriter_get_offered_deadline_missed_status	(	DDS_DataWriter	dw,
		DDS_OfferedDeadlineMissedStatus *	status
	)

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

DDS_ReturnCode_t DDS_DataWriter_get_offered_incompatible_qos_status	(	DDS_DataWriter	dw,
		DDS_OfferedIncompatibleQosStatus *	status
	)

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

DDS_ReturnCode_t DDS_DataWriter_get_publication_matched_status	(	DDS_DataWriter	dw,
		DDS_PublicationMatchedStatus *	status
	)

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

DDS_ReturnCode_t DDS_DataWriter_get_qos	(	DDS_DataWriter	dw,
		DDS_DataWriterQos *	qos
	)

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

DDS_StatusMask DDS_DataWriter_get_status_changes ( DDS_DataWriter dw )

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

DDS_StatusCondition DDS_DataWriter_get_statuscondition ( DDS_DataWriter dw )

The returned condition can be added to a DDS_WaitSet.

DDS_InstanceHandle_t DDS_DataWriter_lookup_instance	(	DDS_DataWriter	dw,
		const void *	instance_data
	)

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

DDS_InstanceHandle_t DDS_DataWriter_register_instance	(	DDS_DataWriter	dw,
		const void *	instance_data
	)

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

DDS_InstanceHandle_t DDS_DataWriter_register_instance_w_timestamp	(	DDS_DataWriter	dw,
		const void *	instance_data,
		const DDS_Time_t	source_timestamp
	)

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

DDS_ReturnCode_t DDS_DataWriter_set_listener	(	DDS_DataWriter	dw,
		DDS_DataWriterListener *	a_listener,
		DDS_StatusMask	mask
	)

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.

DDS_ReturnCode_t DDS_DataWriter_set_listener_cd	(	DDS_DataWriter	dw,
		DDS_DataWriterListener_cd *	a_listener,
		DDS_StatusMask	mask,
		void *	callback_data
	)

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

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

The infrastructure will hold a pointer to the listener structure which means that it must be persisted by the application.

DDS_ReturnCode_t DDS_DataWriter_set_qos	(	DDS_DataWriter	dw,
		const DDS_DataWriterQos *	qos
	)

These QoS values affect the behavior of the DDS_DataWriter.

DDS_ReturnCode_t DDS_DataWriter_unregister_instance	(	DDS_DataWriter	dw,
		const void *	instance_data,
		const DDS_InstanceHandle_t	handle
	)

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.

DDS_ReturnCode_t DDS_DataWriter_unregister_instance_w_timestamp	(	DDS_DataWriter	dw,
		const void *	instance_data,
		DDS_InstanceHandle_t	handle,
		const DDS_Time_t	source_timestamp
	)

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.

DDS_ReturnCode_t DDS_DataWriter_wait_for_acknowledgments	(	DDS_DataWriter	dw,
		const DDS_Duration_t *	max_wait
	)

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

DDS_RETCODE_TIME_OUT	returned if 'max_wait' passes before all acks are received
DDS_RETCODE_OK	returned if all acks have been received before 'max_wait'

DDS_ReturnCode_t DDS_DataWriter_write	(	DDS_DataWriter	dw,
		const void *	instance_data,
		const DDS_InstanceHandle_t	handle
	)

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 DDS_RETCODE_TIMEOUT is returned.

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

On success, DDS_RETCODE_OK is returned.

DDS_ReturnCode_t DDS_DataWriter_write_w_timestamp	(	DDS_DataWriter	dw,
		const void *	instance_data,
		const DDS_InstanceHandle_t	handle,
		const DDS_Time_t	source_timestamp
	)

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 DDS_RETCODE_TIMEOUT is returned.

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

On success, DDS_RETCODE_OK is returned.

Related Functions

Detailed Description

Friends And Related Function Documentation