DDS_DataWriter entity and associated elements More...

Data Structures
struct	FooDataWriter
	<<interface>> <<generic>> User data type specific data writer.Defines the user data type specific writer interface generated for each application class. More...
struct	DDS_OfferedDeadlineMissedStatus
	<<cert>> DDS_OFFERED_DEADLINE_MISSED_STATUS More...
struct	DDS_LivelinessLostStatus
	<<cert>> DDS_LIVELINESS_LOST_STATUS More...
struct	DDS_OfferedIncompatibleQosStatus
	<<cert>> DDS_OFFERED_INCOMPATIBLE_QOS_STATUS More...
struct	DDS_PublicationMatchedStatus
	<<cert>> DDS_PUBLICATION_MATCHED_STATUSA "match" happens when the DDS_DataWriter finds a DDS_DataReader for the same DDS_Topic and common partition with a requested QoS that is compatible with that offered by the DDS_DataWriter. More...
struct	DDS_ReliableReaderActivityChangedStatus
	<<eXtension>> <<cert>> Describes the activity (i.e. are acknowledgements forthcoming) of reliable readers matched to a reliable writer. More...
struct	DDS_DataWriterQos
	<<cert>> QoS policies supported by a DDS_DataWriter entity. More...
struct	DDS_DataWriterListener
	<<interface>> <<cert>> DDS_Listener for writer status. More...

Macros
#define	DDS_OfferedDeadlineMissedStatus_INITIALIZER
	<<cert>> Initializer for new status instances.
#define	DDS_LivelinessLostStatus_INITIALIZER
	<<cert>> Initializer for new status instances.
#define	DDS_OfferedIncompatibleQosStatus_INITIALIZER
	<<cert>> Initializer for new status instances.
#define	DDS_PublicationMatchedStatus_INITIALIZER
	<<cert>> Initializer for new status instances.
#define	DDS_ReliableReaderActivityChangedStatus_INITIALIZER
	<<cert>> Initializer for new status instances.
#define	DDS_DataWriterQos_INITIALIZER
	<<cert>> Initializer for new QoS instances.
#define	DDS_DataWriterListener_INITIALIZER
	<<cert>> Initializer for new DDS_DataWriterListener.All the new DDS_DataWriterListener instances allocated in the stack should be initialized to this value.No memory is allocated.

Typedefs
typedef struct DDS_DataWriterImpl	DDS_DataWriter
	<<interface>> <<cert>> Allows an application to set the value of the data to be published under a given DDS_Topic.
typedef void(*	DDS_DataWriterListener_OfferedDeadlineMissedCallback )(void listener_data, DDS_DataWriter writer, const struct DDS_OfferedDeadlineMissedStatus *status)
	<<cert>> Prototype of a DDS_DataWriterListener on_offered_deadline_missed function.
typedef void(*	DDS_DataWriterListener_LivelinessLostCallback )(void listener_data, DDS_DataWriter writer, const struct DDS_LivelinessLostStatus *status)
	<<cert>> Prototype of a DDS_DataWriterListener on_liveliness_lost function.
typedef void(*	DDS_DataWriterListener_OfferedIncompatibleQosCallback )(void listener_data, DDS_DataWriter writer, const struct DDS_OfferedIncompatibleQosStatus *status)
	<<cert>> Prototype of a DDS_DataWriterListener on_offered_incompatible_qos function.
typedef void(*	DDS_DataWriterListener_PublicationMatchedCallback )(void listener_data, DDS_DataWriter writer, const struct DDS_PublicationMatchedStatus *status)
	<<cert>> Prototype of a DDS_DataWriterListener on_publication_matched function.
typedef void(*	DDS_DataWriterListener_ReliableReaderActivityChangedCallback )(void listener_data, DDS_DataWriter writer, const struct DDS_ReliableReaderActivityChangedStatus *status)
	<<eXtension>> <<cert>> A matched reliable reader has become active or become inactive.

Functions
FooDataWriter *	FooDataWriter_narrow (DDS_DataWriter *writer)
	Narrow the given DDS_DataWriter pointer to a FooDataWriter pointer.Check if the given `writer` is of type FooDataWriter.
DDS_DataWriter *	FooDataWriter_as_datawriter (FooDataWriter *writer)
	Widen the given FooDataWriter pointer to a DDS_DataWriter pointer.
DDS_InstanceHandle_t	FooDataWriter_register_instance (FooDataWriter self, const void instance_data)
	Informs RTI Connext Micro that the application will be modifying a particular instance.This operation is only useful for keyed data types. Using it for non-keyed types causes no effect and returns DDS_HANDLE_NIL. The operation takes as a parameter an instance (of which only the key value is examined) and returns a `handle` that can be used in successive write() or dispose() operations.
DDS_InstanceHandle_t	FooDataWriter_register_instance_w_timestamp (FooDataWriter self, const void instance_data, const struct DDS_Time_t *source_timestamp)
	Performs the same functions as register_instance except that the application provides the value for the `source_timestamp`.The provided `source_timestamp` potentially affects the relative order in which readers observe events from multiple writers.
DDS_ReturnCode_t	FooDataWriter_unregister_instance (FooDataWriter self, const void instance_data, const DDS_InstanceHandle_t *handle)
	Reverses the action of FooDataWriter_register_instance.This operation is useful only for keyed data types. Using it for non-keyed types causes no effect and reports no error. The operation takes as a parameter an instance (of which only the key value is examined) and a handle.
DDS_ReturnCode_t	FooDataWriter_unregister_instance_w_timestamp (FooDataWriter self, const void instance_data, const DDS_InstanceHandle_t handle, const struct DDS_Time_t source_timestamp)
	Performs the same function as FooDataWriter_unregister_instance except that it also provides the value for the `source_timestamp`.The provided `source_timestamp` potentially affects the relative order in which readers observe events from multiple writers.
DDS_ReturnCode_t	FooDataWriter_dispose (FooDataWriter self, const void instance_data, const DDS_InstanceHandle_t *handle)
	Requests the middleware to delete the data.
DDS_ReturnCode_t	FooDataWriter_dispose_w_timestamp (FooDataWriter self, const void instance_data, const DDS_InstanceHandle_t handle, const struct DDS_Time_t source_timestamp)
	Performs the same functions as dispose except that the application provides the value for the `source_timestamp` that is made available to DDS_DataReader objects by means of the `source_timestamp` attribute inside the DDS_SampleInfo.The constraints on the values of the `handle` parameter and the corresponding error behavior are the same specified for the FooDataWriter_dispose operation.
DDS_ReturnCode_t	FooDataWriter_write (FooDataWriter self, const void instance_data, const DDS_InstanceHandle_t *handle)
	Modifies the value of a data instance.
DDS_ReturnCode_t	FooDataWriter_write_w_timestamp (FooDataWriter self, const void instance_data, const DDS_InstanceHandle_t handle, const struct DDS_Time_t source_timestamp)
	Performs the same function as FooDataWriter_write except that it also provides the value for the `source_timestamp`.Explicitly provides the timestamp that will be available to the DDS_DataReader objects by means of the `source_timestamp` attribute inside the DDS_SampleInfo. (Refer to DDS_SampleInfo details)
DDS_ReturnCode_t	DDS_DataWriterQos_initialize (struct DDS_DataWriterQos *self)
	Initializer for new QoS instances.
DDS_ReturnCode_t	DDS_DataWriterQos_copy (struct DDS_DataWriterQos self, const struct DDS_DataWriterQos source)
	Copy the contents of the given QoS into this QoS.DDS_DataWriterQos instances can use dynamic memory because of the sequences contained in some QoS policies. A shallow copy by assignment is therefore unsafe. This method performs a deep-copy, allocating memory if necessary.
DDS_ReturnCode_t	DDS_DataWriterQos_finalize (struct DDS_DataWriterQos *self)
	Free any dynamic memory allocated by the policies in this DDS_DataWriterQos.Some QoS policies may use dynamic memory (regardless of whether the QoS itself is in dynamic memory). This method frees that memory but otherwise leaves this QoS unchanged. It should be called on all instances before they are freed (or, in the case of stack-based instances, before they go out of scope).
DDS_Entity *	DDS_DataWriter_as_entity (DDS_DataWriter *dataWriter)
	<<cert>> Access a DDS_DataWriter's supertype instance.
DDS_ReturnCode_t	DDS_DataWriter_enable (DDS_Entity *self)
	<<cert>> Enables a DDS_DataWriter instance.
DDS_ReturnCode_t	DDS_DataWriter_assert_liveliness (DDS_DataWriter *self)
	<<cert>> This operation manually asserts the liveliness of this DDS_DataWriter.This is used in combination with the LIVELINESS policy to indicate to RTI Connext Micro that the DDS_DataWriter remains active.
DDS_Topic *	DDS_DataWriter_get_topic (DDS_DataWriter *self)
	<<cert>> This operation returns the DDS_Topic associated with the DDS_DataWriter.This is the same DDS_Topic that was used to create the DDS_DataWriter.
DDS_Publisher *	DDS_DataWriter_get_publisher (DDS_DataWriter *self)
	<<cert>> This operation returns the DDS_Publisher to which the DDS_DataWriter belongs.
DDS_ReturnCode_t	DDS_DataWriter_get_liveliness_lost_status (DDS_DataWriter self, struct DDS_LivelinessLostStatus status)
	<<cert>> Accesses the DDS_LIVELINESS_LOST_STATUS communication status.
DDS_ReturnCode_t	DDS_DataWriter_get_offered_deadline_missed_status (DDS_DataWriter self, struct DDS_OfferedDeadlineMissedStatus status)
	<<cert>> Accesses the DDS_OFFERED_DEADLINE_MISSED_STATUS communication status.
DDS_ReturnCode_t	DDS_DataWriter_get_offered_incompatible_qos_status (DDS_DataWriter self, struct DDS_OfferedIncompatibleQosStatus status)
	<<cert>> Accesses the DDS_OFFERED_INCOMPATIBLE_QOS_STATUS communication status.
DDS_ReturnCode_t	DDS_DataWriter_get_publication_matched_status (DDS_DataWriter self, struct DDS_PublicationMatchedStatus status)
	<<cert>> Accesses the DDS_PUBLICATION_MATCHED_STATUS communication status.
DDS_ReturnCode_t	DDS_DataWriter_get_reliable_reader_activity_changed_status (DDS_DataWriter self, struct DDS_ReliableReaderActivityChangedStatus status)
	<<cert>> Get the reliable reader activity changed status for this writer.
DDS_ReturnCode_t	DDS_DataWriter_set_qos (DDS_DataWriter self, const struct DDS_DataWriterQos qos)
	Sets the writer QoS.
DDS_ReturnCode_t	DDS_DataWriter_get_qos (DDS_DataWriter self, struct DDS_DataWriterQos qos)
	Gets the writer QoS.
DDS_ReturnCode_t	DDS_DataWriter_set_listener (DDS_DataWriter self, const struct DDS_DataWriterListener l, DDS_StatusMask mask)
	Sets the writer listener.
struct DDS_DataWriterListener	DDS_DataWriter_get_listener (DDS_DataWriter *self)
	Get the writer listener.
DDS_InstanceHandle_t	DDS_DataWriter_register_instance (DDS_DataWriter self, const void instance_data)
	<<cert>> Informs RTI Connext Micro that the application will be modifying a particular instance.This operation is only useful for keyed data types. Using it for non-keyed types causes no effect and returns DDS_HANDLE_NIL. The operation takes as a parameter an instance (of which only the key value is examined) and returns a `handle` that can be used in successive write() or dispose() operations.
DDS_InstanceHandle_t	DDS_DataWriter_register_instance_w_timestamp (DDS_DataWriter self, const void instance_data, const struct DDS_Time_t *source_timestamp)
	<<cert>> Performs the same function as DDS_DataWriter_register_instance except that it also provides the value for the `source_timestamp`.
DDS_ReturnCode_t	DDS_DataWriter_unregister_instance (DDS_DataWriter self, const void instance_data, const DDS_InstanceHandle_t *handle)
	<<cert>> Reverses the action of DDS_DataWriter_register_instance.This operation is useful only for keyed data types. Using it for non-keyed types causes no effect and reports no error. The operation takes as a parameter an instance (of which only the key value is examined) and a handle.
DDS_ReturnCode_t	DDS_DataWriter_unregister_instance_w_timestamp (DDS_DataWriter self, const void instance_data, const DDS_InstanceHandle_t handle, const struct DDS_Time_t source_timestamp)
	<<cert>> Performs the same function as DDS_DataWriter_unregister_instance except that it also provides the value for the `source_timestamp`.Explicitly provides the timestamp that will be available to the DDS_DataReader objects by means of the `source_timestamp` attribute inside the DDS_SampleInfo. (Refer to DDS_SampleInfo for details)
DDS_ReturnCode_t	DDS_DataWriter_dispose (DDS_DataWriter self, const void instance_data, const DDS_InstanceHandle_t *handle)
	<<cert>> Requests the middleware to delete the data.
DDS_ReturnCode_t	DDS_DataWriter_dispose_w_timestamp (DDS_DataWriter self, const void instance_data, const DDS_InstanceHandle_t handle, const struct DDS_Time_t source_timestamp)
	<<cert>> Performs the same function as DDS_DataWriter_dispose except that it also provides the value for the `source_timestamp`.
DDS_ReturnCode_t	DDS_DataWriter_write (DDS_DataWriter self, const void instance_data, const DDS_InstanceHandle_t *handle)
	<<cert>> Modifies the value of a data instance.
DDS_ReturnCode_t	DDS_DataWriter_write_w_timestamp (DDS_DataWriter self, const void instance_data, const DDS_InstanceHandle_t handle, const struct DDS_Time_t source_timestamp)
	<<cert>> Performs the same function as DDS_DataWriter_write except that it also provides the value for the `source_timestamp`.Explicitly provides the timestamp that will be available to the DDS_DataReader objects by means of the `source_timestamp` attribute inside the DDS_SampleInfo. (Refer to DDS_SampleInfo for details)
DDS_ReturnCode_t	DDS_DataWriter_write_w_params (DDS_DataWriter self, const void instance_data, struct DDS_WriteParams_t *params)
	Publish a data sample using the given set of additional parameters.

Detailed Description

DDS_DataWriter entity and associated elements

Macro Definition Documentation

#define DDS_OfferedDeadlineMissedStatus_INITIALIZER

<<cert>> Initializer for new status instances.

New DDS_OfferedDeadlineMissedStatus instances stored on the stack should be initialized with this value before they are passed to any method . This step ensures that those fields that use dynamic memory are properly initialized. This does not allocate memory.

The simplest way to create a status structure is to initialize it on the stack at the time of its creation.

#define DDS_LivelinessLostStatus_INITIALIZER

<<cert>> Initializer for new status instances.

New DDS_LivelinessLostStatus instances stored on the stack should be initialized with this value before they are passed to any method . This step ensures that those fields that use dynamic memory are properly initialized. This does not allocate memory.

The simplest way to create a status structure is to initialize it on the stack at the time of its creation.

#define DDS_OfferedIncompatibleQosStatus_INITIALIZER

<<cert>> Initializer for new status instances.

New DDS_OfferedIncompatibleQosStatus instances stored on the stack should be initialized with this value before they are passed to any method . This step ensures that those fields that use dynamic memory are properly initialized. This does not allocate memory.

The simplest way to create a status structure is to initialize it on the stack at the time of its creation.

#define DDS_PublicationMatchedStatus_INITIALIZER

<<cert>> Initializer for new status instances.

New DDS_PublicationMatchedStatus instances stored on the stack should be initialized with this value before they are passed to any method . This step ensures that those fields that use dynamic memory are properly initialized. This does not allocate memory.

The simplest way to create a status structure is to initialize it on the stack at the time of its creation.

#define DDS_ReliableReaderActivityChangedStatus_INITIALIZER

<<cert>> Initializer for new status instances.

New DDS_ReliableReaderActivityChangedStatus instances stored on the stack should be initialized with this value before they are passed to any method . This step ensures that those fields that use dynamic memory are properly initialized. This does not allocate memory.

The simplest way to create a status structure is to initialize it on the stack at the time of its creation.

#define DDS_DataWriterQos_INITIALIZER

<<cert>> Initializer for new QoS instances.

New DDS_DataWriterQos instances stored on the stack should be initialized with this value before they are passed to any method . This step ensures that those contained QoS policies that use dynamic memory are properly initialized. This does not allocate memory.

The simplest way to create a new QoS structure is to initialize it on the stack at the time of its creation:

DDS_DataWriterQos myQos = DDS_DataWriterQos_INITIALIZER;

See also:: DDS_DataWriterQos_finalize

#define DDS_DataWriterListener_INITIALIZER

<<cert>> Initializer for new DDS_DataWriterListener.All the new DDS_DataWriterListener instances allocated in the stack should be initialized to this value.No memory is allocated.

 DDS_DataWriterListener listener = DDS_DataWriterListener_INITIALIZER;
  /* initialize listener functions */ 
  listener.on_offered_deadline_missed = ....; 
  DDS_DataWriter_set_listener(myDataWriter, &listener, mask);

See also:: DDS_DataWriter_set_listener; DDS_DataWriterListener

Typedef Documentation

typedef struct DDS_DataWriterImpl DDS_DataWriter

<<interface>> <<cert>> Allows an application to set the value of the data to be published under a given DDS_Topic.

QoS:: DDS_DataWriterQos

Status:: DDS_LIVELINESS_LOST_STATUS, DDS_LivelinessLostStatus;
DDS_OFFERED_DEADLINE_MISSED_STATUS, DDS_OfferedDeadlineMissedStatus;
DDS_OFFERED_INCOMPATIBLE_QOS_STATUS, DDS_OfferedIncompatibleQosStatus;
DDS_PUBLICATION_MATCHED_STATUS, DDS_PublicationMatchedStatus;

Listener:: DDS_DataWriterListener

A DDS_DataWriter is attached to exactly one DDS_Publisher, that acts as a factory for it.

A DDS_DataWriter is bound to exactly one DDS_Topic and therefore to exactly one data type. The DDS_Topic must exist prior to the DDS_DataWriter's creation.

DDS_DataWriter is an abstract class. It must be specialized for each particular application data-type. The additional methods or functions that must be defined in the auto-generated class for a hypothetical application type Foo are specified in the example type DDS_DataWriter.

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

Several DDS_DataWriter may operate in different threads. If they share the same DDS_Publisher, the middleware guarantees that its operations are thread-safe.

typedef void(* DDS_DataWriterListener_OfferedDeadlineMissedCallback)(void *listener_data, DDS_DataWriter *writer, const struct DDS_OfferedDeadlineMissedStatus *status)

<<cert>> Prototype of a DDS_DataWriterListener on_offered_deadline_missed function.

typedef void(* DDS_DataWriterListener_LivelinessLostCallback)(void *listener_data, DDS_DataWriter *writer, const struct DDS_LivelinessLostStatus *status)

<<cert>> Prototype of a DDS_DataWriterListener on_liveliness_lost function.

Parameters:

listener_data	<<out>> Data associated with the listener when the listener is set
writer	<<out>> Locally created DDS_DataWriter that triggers the listener callback
status	<<out>> Current liveliness lost status of the locally created DDS_DataWriter

typedef void(* DDS_DataWriterListener_OfferedIncompatibleQosCallback)(void *listener_data, DDS_DataWriter *writer, const struct DDS_OfferedIncompatibleQosStatus *status)

<<cert>> Prototype of a DDS_DataWriterListener on_offered_incompatible_qos function.

Parameters:

listener_data	<<out>> Data associated with the listener when the listener is set
writer	<<out>> Locally created DDS_DataWriter that triggers the listener callback
status	<<out>> Current offered incompatible qos status of the locally created DDS_DataWriter

typedef void(* DDS_DataWriterListener_PublicationMatchedCallback)(void *listener_data, DDS_DataWriter *writer, const struct DDS_PublicationMatchedStatus *status)

<<cert>> Prototype of a DDS_DataWriterListener on_publication_matched function.

typedef void(* DDS_DataWriterListener_ReliableReaderActivityChangedCallback)(void *listener_data, DDS_DataWriter *writer, const struct DDS_ReliableReaderActivityChangedStatus *status)

<<eXtension>> <<cert>> A matched reliable reader has become active or become inactive.

Parameters:

listener_data	<<out>> Data associated with the listener when the listener is set
writer	<<out>> Locally created DDS_DataWriter that triggers the listener callback
status	<<out>> Current reliable reader activity changed status of the locally created DDS_DataWriter

Function Documentation

FooDataWriter* FooDataWriter_narrow ( DDS_DataWriter * writer )

Narrow the given DDS_DataWriter pointer to a FooDataWriter pointer.Check if the given writer is of type FooDataWriter.

Parameters:

writer <<in>> Base-class DDS_DataWriter to be converted to the auto-generated class FooDataWriter that extends DDS_DataWriter.

Returns:: FooDataWriter if writer is of type Foo. Return NULL otherwise.

DDS_DataWriter* FooDataWriter_as_datawriter ( FooDataWriter * writer )

Widen the given FooDataWriter pointer to a DDS_DataWriter pointer.

Parameters:

writer <<in>> auto-generated FooDataWriter to be converted to the Base-class DDS_DataWriter.

Returns:: DDS_DataWriter.

DDS_InstanceHandle_t FooDataWriter_register_instance	(	FooDataWriter *	self,
		const void *	instance_data
	)

Informs RTI Connext Micro that the application will be modifying a particular instance.This operation is only useful for keyed data types. Using it for non-keyed types causes no effect and returns DDS_HANDLE_NIL. The operation takes as a parameter an instance (of which only the key value is examined) and returns a handle that can be used in successive write() or dispose() operations.

The operation gives RTI Connext Micro an opportunity to pre-configure itself to improve performance.

The use of this operation by an application is optional even for keyed types. If an instance has not been pre-registered, the application can use the special value DDS_HANDLE_NIL as the DDS_InstanceHandle_t paramater to the write or dispose operation and RTI Connext Micro will auto-register the instance.

For best performance, the operation should be invoked prior to calling any operation that modifies the instance, such as FooDataWriter_write, FooDataWriter_write_w_timestamp, FooDataWriter_dispose and FooDataWriter_dispose_w_timestamp and the handle used in conjunction with the data for those calls.

When this operation is used, RTI Connext Micro will automatically supply the value of the source_timestamp that is used.

This operation may fail and return DDS_HANDLE_NIL if DDS_ResourceLimitsQosPolicy::max_instances limit has been exceeded.

The operation is idempotent. If it is called for an already registered instance, it just returns the already allocated handle. This may be used to lookup and retrieve the handle allocated to a given instance.

This operation can only be called after DDS_DataWriter has been enabled. Otherwise, DDS_HANDLE_NIL will be returned.

Parameters:

instance_data <<in>> The instance that should be registered. Of this instance, only the fields that represent the key are examined by the function. Cannot be NULL..

Returns:: For keyed data type, a handle that can be used in the calls that take a DDS_InstanceHandle_t, such as write, dispose, unregister_instance, or return DDS_HANDLE_NIL on failure. If the instance_data is of a data type that has no keys, this function always return DDS_HANDLE_NIL.

See also:: FooDataWriter_unregister_instance

DDS_InstanceHandle_t FooDataWriter_register_instance_w_timestamp	(	FooDataWriter *	self,
		const void *	instance_data,
		const struct DDS_Time_t *	source_timestamp
	)

Performs the same functions as register_instance except that the application provides the value for the source_timestamp.The provided source_timestamp potentially affects the relative order in which readers observe events from multiple writers.

This operation may fail and return DDS_HANDLE_NIL if DDS_ResourceLimitsQosPolicy::max_instances limit has been exceeded.

This operation can only be called after DDS_DataWriter has been enabled. Otherwise, DDS_HANDLE_NIL will be returned.

Parameters:

instance_data	<<in>> The instance that should be registered. Of this instance, only the fields that represent the key are examined by the function. Cannot be NULL.
source_timestamp	<<in>> The timestamp value must be greater than or equal to the timestamp value used in the last writer operation (used in a register, unregister, dispose, or write, with either the automatically supplied timestamp or the application provided timestamp). This timestamp may potentially affect the order in which readers observe events from multiple writers. Cannot be NULL.

Returns:: For keyed data type, return a handle that can be used in the calls that take a DDS_InstanceHandle_t, such as write, dispose, unregister_instance, or return DDS_HANDLE_NIL on failure. If the instance_data is of a data type that has no keys, this function always return DDS_HANDLE_NIL.

See also:: FooDataWriter_unregister_instance

DDS_ReturnCode_t FooDataWriter_unregister_instance	(	FooDataWriter *	self,
		const void *	instance_data,
		const DDS_InstanceHandle_t *	handle
	)

Reverses the action of FooDataWriter_register_instance.This operation is useful only for keyed data types. Using it for non-keyed types causes no effect and reports no error. The operation takes as a parameter an instance (of which only the key value is examined) and a handle.

This operation should only be called on an instance that is currently registered. This includes instances that have been auto-registered by calling operations such as write or dispose as described in FooDataWriter_register_instance. Otherwise, this operation may fail with DDS_RETCODE_BAD_PARAMETER.

This only need be called just once per instance, regardless of how many times register_instance was called for that instance.

When this operation is used, RTI Connext Micro will automatically supply the value of the source_timestamp that is used.

This operation informs RTI Connext Micro that the DDS_DataWriter is no longer going to provide any information about the instance. This operation also indicates that RTI Connext Micro can locally remove all information regarding that instance. The application should not attempt to use the handle previously allocated to that instance after calling FooDataWriter_unregister_instance().

The special value DDS_HANDLE_NIL can be used for the parameter handle. This indicates that the identity of the instance should be automatically deduced from the instance_data (by means of the key).

If handle is any value other than DDS_HANDLE_NIL, then it must correspond to an instance that has been registered. If there is no correspondence, the operation will fail with DDS_RETCODE_BAD_PARAMETER.

RTI Connext Micro will not detect the error when the handle is any value other than DDS_HANDLE_NIL, corresponds to an instance that has been registered, but does not correspond to the instance deduced from the instance_data (by means of the key). RTI Connext Micro will treat as if the unregister_instance() operation is for the instance as indicated by the handle.

If after a FooDataWriter_unregister_instance, the application wants to modify (FooDataWriter_write or FooDataWriter_dispose) an instance, it has to register it again, or else use the special handle value DDS_HANDLE_NIL.

This operation does not indicate that the instance is deleted (that is the purpose of FooDataWriter_dispose). The operation FooDataWriter_unregister_instance just indicates that the DDS_DataWriter no longer has anything to say about the instance. DDS_DataReader entities that are reading the instance may receive a sample with DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE for the instance, unless there are other DDS_DataWriter objects writing that same instance.

This operation can affect the ownership of the data instance (see OWNERSHIP). If the DDS_DataWriter was the exclusive owner of the instance, then calling unregister_instance() will relinquish that ownership.

If DDS_ReliabilityQosPolicy::kind is set to DDS_RELIABLE_RELIABILITY_QOS and the unregistration would overflow the resource limits of this writer or of a reader, this operation may block for up to DDS_ReliabilityQosPolicy::max_blocking_time; if this writer is still unable to unregister after that period, this method will fail with DDS_RETCODE_TIMEOUT.

Parameters:

instance_data <<in>> The instance that should be unregistered. If Foo has a key and instance_handle is DDS_HANDLE_NIL, only the fields that represent the key are examined by the function. Otherwise, instance_data is not used. If instance_data is used, it must represent an instance that has been registerd. Otherwise, this method may fail with DDS_RETCODE_BAD_PARAMETER . If Foo has a key, instance_data can be NULL only if handle is not DDS_HANDLE_NIL. Otherwise, this method will fail with DDS_RETCODE_BAD_PARAMETER.

handle <<in>> represents the instance to be unregistered. If Foo has a key and handle is DDS_HANDLE_NIL, handle is not used and instance is deduced from instance_data. If Foo has no key, handle is not used. If handle is used, it must represent an instance that has been registered. Otherwise, this method may fail with DDS_RETCODE_BAD_PARAMETER. This method will fail with DDS_RETCODE_BAD_PARAMETER if handle is NULL. If Foo has a key, handle cannot be DDS_HANDLE_NIL if instance_data is NULL. Otherwise, this method will report the error DDS_RETCODE_BAD_PARAMETER.

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

See also:: FooDataWriter_register_instance; FooDataWriter_unregister_instance_w_timestamp

DDS_ReturnCode_t FooDataWriter_unregister_instance_w_timestamp	(	FooDataWriter *	self,
		const void *	instance_data,
		const DDS_InstanceHandle_t *	handle,
		const struct DDS_Time_t *	source_timestamp
	)

Performs the same function as FooDataWriter_unregister_instance except that it also provides the value for the source_timestamp.The provided source_timestamp potentially affects the relative order in which readers observe events from multiple writers.

The constraints on the values of the handle parameter and the corresponding error behavior are the same specified for the FooDataWriter_unregister_instance operation.

This operation may block and may time out (DDS_RETCODE_TIMEOUT) under the same circumtances described for the unregister_instance operation.

Parameters:

instance_data	<<in>> The instance that should be unregistered. If Foo has a key and `instance_handle` is DDS_HANDLE_NIL, only the fields that represent the key are examined by the function. Otherwise, `instance_data` is not used. If `instance_data` is used, it must represent an instance that has been registerd. Otherwise, this method may fail with DDS_RETCODE_BAD_PARAMETER. If Foo has a key, `instance_data` can be NULL only if `handle` is not DDS_HANDLE_NIL. Otherwise, this method will fail with DDS_RETCODE_BAD_PARAMETER.
handle	<<in>> represents the `instance` to be unregistered. If Foo has a key and `handle` is DDS_HANDLE_NIL, `handle` is not used and `instance` is deduced from `instance_data`. If Foo has no key, `handle` is not used. If `handle` is used, it must represent an instance that has been registered. Otherwise, this method may fail with DDS_RETCODE_BAD_PARAMETER. This method will fail with DDS_RETCODE_BAD_PARAMETER if `handle` is NULL. If Foo has a key, `handle` cannot be DDS_HANDLE_NIL if `instance_data` is NULL. Otherwise, this method will fail with DDS_RETCODE_BAD_PARAMETER.
source_timestamp	<<in>> The timestamp value must be greater than or equal to the timestamp value used in the last writer operation (used in a register, unregister, dispose, or write, with either the automatically supplied timestamp or the application provided timestamp). This timestamp may potentially affect the order in which readers observe events from multiple writers. Cannot be NULL.

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

See also:: FooDataWriter_register_instance; FooDataWriter_unregister_instance

DDS_ReturnCode_t FooDataWriter_dispose	(	FooDataWriter *	self,
		const void *	instance_data,
		const DDS_InstanceHandle_t *	handle
	)

Requests the middleware to delete the data.

This operation is useful only for keyed data types. Using it for non-keyed types has no effect and reports no error.

The actual deletion is postponed until there is no more use for that data in the whole system.

Applications are made aware of the deletion by means of operations on the DDS_DataReader objects that already knew that instance. DDS_DataReader objects that didn't know the instance will never see it.

This operation does not modify the value of the instance. The instance_data parameter is passed just for the purposes of identifying the instance.

When this operation is used, RTI Connext Micro will automatically supply the value of the source_timestamp that is made available to DDS_DataReader objects by means of the source_timestamp attribute inside the DDS_SampleInfo.

The constraints on the values of the handle parameter and the corresponding error behavior are the same specified for the FooDataWriter_unregister_instance operation.

The special value DDS_HANDLE_NIL can be used for the parameter instance_handle. This indicates the identity of the instance should be automatically deduced from the instance_data (by means of the key).

If handle is any value other than DDS_HANDLE_NIL, then it must correspond to an instance that has been registered. If there is no correspondence, the operation will fail with DDS_RETCODE_BAD_PARAMETER.

RTI Connext Micro will not detect the error when the handle is any value other than DDS_HANDLE_NIL, corresponds to an instance that has been registered, but does not correspond to the instance deduced from the instance_data (by means of the key). RTI Connext Micro will treat as if the dispose() operation is for the instance as indicated by the handle.

This operation may block and time out (DDS_RETCODE_TIMEOUT) under the same circumtances described for FooDataWriter_write().

If there are no instance resources left, this operation may fail with DDS_RETCODE_OUT_OF_RESOURCES. Calling FooDataWriter_unregister_instance may help freeing up some resources.

Parameters:

instance_data <<in>> The data to dispose. If Foo has a key and instance_handle is DDS_HANDLE_NIL, only the fields that represent the key are examined by the function. Otherwise, instance_data is not used. If Foo has a key, instance_data can be NULL only if instance_handle is not DDS_HANDLE_NIL. Otherwise, this method will fail with DDS_RETCODE_BAD_PARAMETER.

handle <<in>> Either the handle returned by a previous call to FooDataWriter_register_instance, or else the special value DDS_HANDLE_NIL. If Foo has a key and instance_handle is DDS_HANDLE_NIL, instance_handle is not used and instance is deduced from instance_data. If Foo has no key, instance_handle is not used. If handle is used, it must represent a registered instance of type Foo. Otherwise, this method fail with DDS_RETCODE_BAD_PARAMETER. This method will fail with DDS_RETCODE_BAD_PARAMETER if handle is NULL. If Foo has a key, instance_handle cannot be DDS_HANDLE_NIL if instance_data is NULL. Otherwise, this method will fail with DDS_RETCODE_BAD_PARAMETER.

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

See also:: FooDataWriter_dispose_w_timestamp

DDS_ReturnCode_t FooDataWriter_dispose_w_timestamp	(	FooDataWriter *	self,
		const void *	instance_data,
		const DDS_InstanceHandle_t *	handle,
		const struct DDS_Time_t *	source_timestamp
	)

Performs the same functions as dispose except that the application provides the value for the source_timestamp that is made available to DDS_DataReader objects by means of the source_timestamp attribute inside the DDS_SampleInfo.The constraints on the values of the handle parameter and the corresponding error behavior are the same specified for the FooDataWriter_dispose operation.

This operation may block and time out (DDS_RETCODE_TIMEOUT) under the same circumtances described for FooDataWriter_write.

If there are no instance resources left, this operation may fail with DDS_RETCODE_OUT_OF_RESOURCES. Calling FooDataWriter_unregister_instance may help freeing up some resources.

Parameters:

instance_data	<<in>> The data to dispose. If Foo has a key and `instance_handle` is DDS_HANDLE_NIL, only the fields that represent the key are examined by the function. Otherwise, `instance_data` is not used. If Foo has a key, `instance_data` can be NULL only if `instance_handle` is not DDS_HANDLE_NIL. Otherwise, this method will fail with DDS_RETCODE_BAD_PARAMETER.
handle	<<in>> Either the handle returned by a previous call to FooDataWriter_register_instance, or else the special value DDS_HANDLE_NIL. If Foo has a key and `instance_handle` is DDS_HANDLE_NIL, `instance_handle` is not used and `instance` is deduced from `instance_data`. If Foo has no key, `instance_handle` is not used. If `handle` is used, it must represent a registered instance of type Foo. Otherwise, this method may fail with DDS_RETCODE_BAD_PARAMETER This method will fail with DDS_RETCODE_BAD_PARAMETER if `handle` is NULL. If Foo has a key, `instance_handle` cannot be DDS_HANDLE_NIL if `instance_data` is NULL. Otherwise, this method will fail with DDS_RETCODE_BAD_PARAMETER.
source_timestamp	<<in>> The timestamp value must be greater than or equal to the timestamp value used in the last writer operation (used in a register, unregister, dispose, or write, with either the automatically supplied timestamp or the application provided timestamp). This timestamp may potentially affect the order in which readers observe events from multiple writers. This timestamp will be available to the DDS_DataReader objects by means of the `source_timestamp` attribute inside the DDS_SampleInfo. Cannot be NULL.

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

See also:: FooDataWriter_dispose

DDS_ReturnCode_t FooDataWriter_write	(	FooDataWriter *	self,
		const void *	instance_data,
		const DDS_InstanceHandle_t *	handle
	)

Modifies the value of a data instance.

When this operation is used, RTI Connext Micro will automatically supply the value of the source_timestamp that is made available to DDS_DataReader objects by means of the source_timestamp attribute inside the DDS_SampleInfo. (Refer to DDS_SampleInfo details).

As a side effect, this operation asserts liveliness on the DDS_DataWriter itself, the DDS_Publisher and the DDS_DomainParticipant.

Note that the special value DDS_HANDLE_NIL can be used for the parameter handle. This indicates the identity of the instance should be automatically deduced from the instance_data (by means of the key).

If handle is any value other than DDS_HANDLE_NIL, then it must correspond to an instance that has been registered. If there is no correspondence, the operation will fail with DDS_RETCODE_BAD_PARAMETER.

RTI Connext Micro will not detect the error when the handle is any value other than DDS_HANDLE_NIL, corresponds to an instance that has been registered, but does not correspond to the instance deduced from the instance_data (by means of the key). RTI Connext Micro will treat as if the write() operation is for the instance as indicated by the handle.

This operation may block if the RELIABILITY kind is set to DDS_RELIABLE_RELIABILITY_QOS and the modification would cause data to be lost or else cause one of the limits specified in the RESOURCE_LIMITS to be exceeded.

Specifically, this operation may block in the following situations (note that the list may not be exhaustive), even if its DDS_HistoryQosPolicyKind is DDS_KEEP_LAST_HISTORY_QOS:

If (DDS_ResourceLimitsQosPolicy::max_samples < DDS_ResourceLimitsQosPolicy::max_instances * DDS_HistoryQosPolicy::depth), then in the situation where the max_samples resource limit is exhausted, RTI Connext Micro is allowed to discard samples of some other instance, as long as at least one sample remains for such an instance. If it is still not possible to make space available to store the modification, the writer is allowed to block.
If (DDS_ResourceLimitsQosPolicy::max_samples < DDS_ResourceLimitsQosPolicy::max_instances), then the DataWriter may block regardless of the DDS_HistoryQosPolicy::depth.

If this operation does block for any of the above reasons, the RELIABILITY max_blocking_time configures the maximum time the write operation may block (waiting for space to become available). If max_blocking_time elapses before the DDS_DataWriter is able to store the modification without exceeding the limits, the operation will time out (DDS_RETCODE_TIMEOUT).

If there are no instance resources left, this operation may fail with DDS_RETCODE_OUT_OF_RESOURCES. Calling FooDataWriter_unregister_instance may help freeing up some resources.

Parameters:

instance_data	<<in>> The data to write. This method will fail with DDS_RETCODE_BAD_PARAMETER if `instance_data` is NULL.
handle	<<in>> Either the handle returned by a previous call to FooDataWriter_register_instance, or else the special value DDS_HANDLE_NIL. If Foo has a key and `handle` is not DDS_HANDLE_NIL, `handle` must represent a registered instance of type Foo. Otherwise, this method may fail with DDS_RETCODE_BAD_PARAMETER. This method will fail with DDS_RETCODE_BAD_PARAMETER if `handle` is NULL.

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

See also:: DDS_DataReader; FooDataWriter_write_w_timestamp

DDS_ReturnCode_t FooDataWriter_write_w_timestamp	(	FooDataWriter *	self,
		const void *	instance_data,
		const DDS_InstanceHandle_t *	handle,
		const struct DDS_Time_t *	source_timestamp
	)

Performs the same function as FooDataWriter_write except that it also provides the value for the source_timestamp.Explicitly provides the timestamp that will be available to the DDS_DataReader objects by means of the source_timestamp attribute inside the DDS_SampleInfo. (Refer to DDS_SampleInfo details)

The constraints on the values of the handle parameter and the corresponding error behavior are the same specified for the FooDataWriter_write operation.

This operation may block and time out (DDS_RETCODE_TIMEOUT) under the same circumtances described for FooDataWriter_write.

If there are no instance resources left, this operation may fail with DDS_RETCODE_OUT_OF_RESOURCES. Calling FooDataWriter_unregister_instance may help free up some resources.

This operation may fail with DDS_RETCODE_BAD_PARAMETER under the same circumstances described for the write operation.

Parameters:

instance_data	<<in>> The data to write. This method will fail with DDS_RETCODE_BAD_PARAMETER if `instance_data` is NULL.
handle	<<in>> Either the handle returned by a previous call to FooDataWriter_register_instance, or else the special value DDS_HANDLE_NIL. If Foo has a key and `handle` is not DDS_HANDLE_NIL, `handle` must represent a registered instance of type Foo. Otherwise, this method may fail with DDS_RETCODE_BAD_PARAMETER. This method will fail with DDS_RETCODE_BAD_PARAMETER if `handle` is NULL.
source_timestamp	<<in>> The timestamp value must be greater than or equal to the timestamp value used in the last writer operation (used in a register, unregister, dispose, or write, with either the automatically supplied timestamp or the application provided timestamp). This timestamp may potentially affect the order in which readers observe events from multiple writers. This timestamp will be available to the DDS_DataReader objects by means of the `source_timestamp` attribute inside the DDS_SampleInfo. Cannot be NULL.

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

See also:: FooDataWriter_write; DDS_DataReader

DDS_ReturnCode_t DDS_DataWriterQos_initialize ( struct DDS_DataWriterQos * self )

Initializer for new QoS instances.

New DDS_DataWriterQos instances on heap should be initialized with this method before they are passed to any method . This step ensures that those contained QoS policies that use dynamic memory are properly initialized. This method does not allocate memory.

Returns:: One of the Standard Return Codes

See also:: DDS_DataWriterQos_finalize

DDS_ReturnCode_t DDS_DataWriterQos_copy	(	struct DDS_DataWriterQos *	self,
		const struct DDS_DataWriterQos *	source
	)

Copy the contents of the given QoS into this QoS.DDS_DataWriterQos instances can use dynamic memory because of the sequences contained in some QoS policies. A shallow copy by assignment is therefore unsafe. This method performs a deep-copy, allocating memory if necessary.

Parameters:

source <<in>> The DDS_DataWriterQos to copy from.

Returns:: One of the Standard Return Codes

See also:: DDS_DataWriterQos_INITIALIZER; DDS_DataWriterQos_initialize; DDS_DataWriterQos_finalize

DDS_ReturnCode_t DDS_DataWriterQos_finalize ( struct DDS_DataWriterQos * self )

Free any dynamic memory allocated by the policies in this DDS_DataWriterQos.Some QoS policies may use dynamic memory (regardless of whether the QoS itself is in dynamic memory). This method frees that memory but otherwise leaves this QoS unchanged. It should be called on all instances before they are freed (or, in the case of stack-based instances, before they go out of scope).

This method does not leave this object in an invalid state. It is permissable to clear a QoS and then subsequently allocate new dynamic memory in one or more of its QoS policies.

Note that if this QoS instance is stored in heap memory, calling this method will not call free() on it; the user is responsible for explicitly freeing any heap-based QoS instance after calling this method .

Returns:: One of the Standard Return Codes

See also:: DDS_DataWriterQos_INITIALIZER; DDS_DataWriterQos_initialize

DDS_Entity* DDS_DataWriter_as_entity ( DDS_DataWriter * dataWriter )

<<cert>> Access a DDS_DataWriter's supertype instance.

Parameters:

dataWriter <<in>> Cannot be NULL.

Returns:: The DDS_Entity that is supertype instance of the datawriter.

DDS_ReturnCode_t DDS_DataWriter_enable ( DDS_Entity * self )

<<cert>> Enables a DDS_DataWriter instance.

Returns:: One of the Standard Return Codes

See also:: DDS_Entity_enable

DDS_ReturnCode_t DDS_DataWriter_assert_liveliness ( DDS_DataWriter * self )

<<cert>> This operation manually asserts the liveliness of this DDS_DataWriter.This is used in combination with the LIVELINESS policy to indicate to RTI Connext Micro that the DDS_DataWriter remains active.

You only need to use this operation if the LIVELINESS setting is DDS_MANUAL_BY_TOPIC_LIVELINESS_QOS. Otherwise, it has no effect.

Note: writing data via the DDS_DataWriter_write or DDS_DataWriter_write_w_timestamp operation asserts liveliness on the DDS_DataWriter itself, and its DDS_DomainParticipant. Consequently the use of assert_liveliness() is only needed if the application is not writing data regularly.

Returns:: One of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED

See also:: DDS_LivelinessQosPolicy

DDS_Topic* DDS_DataWriter_get_topic ( DDS_DataWriter * self )

<<cert>> This operation returns the DDS_Topic associated with the DDS_DataWriter.This is the same DDS_Topic that was used to create the DDS_DataWriter.

Returns:: DDS_Topic that was used to create the DDS_DataWriter.

DDS_Publisher* DDS_DataWriter_get_publisher ( DDS_DataWriter * self )

<<cert>> This operation returns the DDS_Publisher to which the DDS_DataWriter belongs.

Returns:: DDS_Publisher to which the DDS_DataWriter belongs.

DDS_ReturnCode_t DDS_DataWriter_get_liveliness_lost_status	(	DDS_DataWriter *	self,
		struct DDS_LivelinessLostStatus *	status
	)

<<cert>> Accesses the DDS_LIVELINESS_LOST_STATUS communication status.

Parameters:

status <<inout>> DDS_LivelinessLostStatus to be filled in. Cannot be NULL.

Returns:: One of the Standard Return Codes

DDS_ReturnCode_t DDS_DataWriter_get_offered_deadline_missed_status	(	DDS_DataWriter *	self,
		struct DDS_OfferedDeadlineMissedStatus *	status
	)

<<cert>> Accesses the DDS_OFFERED_DEADLINE_MISSED_STATUS communication status.

Parameters:

status <<inout>> DDS_OfferedDeadlineMissedStatus to be filled in. Cannot be NULL.

Returns:: One of the Standard Return Codes

DDS_ReturnCode_t DDS_DataWriter_get_offered_incompatible_qos_status	(	DDS_DataWriter *	self,
		struct DDS_OfferedIncompatibleQosStatus *	status
	)

<<cert>> Accesses the DDS_OFFERED_INCOMPATIBLE_QOS_STATUS communication status.

Parameters:

status <<inout>> DDS_OfferedIncompatibleQosStatus to be filled in. Cannot be NULL.

Returns:: One of the Standard Return Codes

DDS_ReturnCode_t DDS_DataWriter_get_publication_matched_status	(	DDS_DataWriter *	self,
		struct DDS_PublicationMatchedStatus *	status
	)

<<cert>> Accesses the DDS_PUBLICATION_MATCHED_STATUS communication status.

Parameters:

status <<inout>> DDS_PublicationMatchedStatus to be filled in. Cannot be NULL.

Returns:: One of the Standard Return Codes

DDS_ReturnCode_t DDS_DataWriter_get_reliable_reader_activity_changed_status	(	DDS_DataWriter *	self,
		struct DDS_ReliableReaderActivityChangedStatus *	status
	)

<<cert>> Get the reliable reader activity changed status for this writer.

Parameters:

status <<inout>> DDS_ReliableReaderActivityChangedStatus to be filled in. Cannot be NULL.

Returns:: One of the Standard Return Codes

DDS_ReturnCode_t DDS_DataWriter_set_qos	(	DDS_DataWriter *	self,
		const struct DDS_DataWriterQos *	qos
	)

Sets the writer QoS.

This operation modifies the QoS of the DDS_DataWriter.

The DDS_DataWriterQos::deadline and DDS_DataWriterQos::ownership_strength, can be changed. The other policies are immutable.

Parameters:

qos <<in>> The DDS_DataWriterQos to be set to. Policies must be consistent. Policies cannot be changed after DDS_DataWriter is enabled. The special value DDS_DATAWRITER_QOS_DEFAULT can be used to indicate that the QoS of the DDS_DataWriter should be changed to match the current default DDS_DataWriterQos set in the DDS_Publisher. Cannot be NULL.

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

See also:: DDS_DataWriterQos for rules on consistency among QoS; set_qos (abstract)

DDS_ReturnCode_t DDS_DataWriter_get_qos	(	DDS_DataWriter *	self,
		struct DDS_DataWriterQos *	qos
	)

Gets the writer QoS.

This method may potentially allocate memory depending on the sequences contained in some QoS policies.

Parameters:

qos	<<inout>> The DDS_DataWriterQos to be filled up. Cannot be NULL.

Returns:: One of the Standard Return Codes

See also:: get_qos (abstract)

DDS_ReturnCode_t DDS_DataWriter_set_listener	(	DDS_DataWriter *	self,
		const struct DDS_DataWriterListener *	l,
		DDS_StatusMask	mask
	)

Sets the writer listener.

Parameters:

l	<<in>> DDS_DataWriterListener to set to
mask	<<in>> DDS_StatusMask associated with the DDS_DataWriterListener. on the listener cannot be NULL if the corresponding status is turned on in the `mask`.

Returns:: One of the Standard Return Codes

See also:: set_listener (abstract)

struct DDS_DataWriterListener DDS_DataWriter_get_listener ( DDS_DataWriter * self )

read

Get the writer listener.

Returns:: DDS_DataWriterListener of the DDS_DataWriter.

See also:: get_listener (abstract)

DDS_InstanceHandle_t DDS_DataWriter_register_instance	(	DDS_DataWriter *	self,
		const void *	instance_data
	)

<<cert>> Informs RTI Connext Micro that the application will be modifying a particular instance.This operation is only useful for keyed data types. Using it for non-keyed types causes no effect and returns DDS_HANDLE_NIL. The operation takes as a parameter an instance (of which only the key value is examined) and returns a handle that can be used in successive write() or dispose() operations.

The operation gives RTI Connext Micro an opportunity to pre-configure itself to improve performance.

The use of this operation by an application is optional even for keyed types. If an instance has not been pre-registered, the application can use the special value DDS_HANDLE_NIL as the DDS_InstanceHandle_t paramater to the write or dispose operation and RTI Connext Micro will auto-register the instance.

For best performance, the operation should be invoked prior to calling any operation that modifies the instance, such as DDS_DataWriter_write, DDS_DataWriter_write_w_timestamp, DDS_DataWriter_dispose and the handle used in conjunction with the data for those calls.

When this operation is used, RTI Connext Micro will automatically supply the value of the source_timestamp that is used.

This operation may fail and return DDS_HANDLE_NIL if DDS_ResourceLimitsQosPolicy::max_instances limit has been exceeded.

The operation is idempotent. If it is called for an already registered instance, it just returns the already allocated handle. This may be used to lookup and retrieve the handle allocated to a given instance.

This operation can only be called after DDS_DataWriter has been enabled. Otherwise, DDS_HANDLE_NIL will be returned.

Parameters:

instance_data <<in>> The instance that should be registered. Of this instance, only the fields that represent the key are examined by the function. Cannot be NULL..

Returns:: For keyed data type, a handle that can be used in the calls that take a DDS_InstanceHandle_t, such as write, dispose, unregister_instance, or return DDS_HANDLE_NIL on failure. If the instance_data is of a data type that has no keys, this function always return DDS_HANDLE_NIL.

See also:: DDS_DataWriter_unregister_instance

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

<<cert>> Performs the same function as DDS_DataWriter_register_instance except that it also provides the value for the source_timestamp.

Explicitly provides the timestamp that will be available to the DDS_DataReader objects by means of the source_timestamp attribute inside the DDS_SampleInfo. (Refer to DDS_SampleInfo for details)

The constraints on the values of the parameters and the corresponding error behavior are the same specified for the DDS_DataWriter_register_instance operation.

Parameters:

instance_data <<in>> The instance that should be registered. Of this instance, only the fields that represent the key are examined by the function. Cannot be NULL..

source_timestamp <<in>> The timestamp value must be greater than or equal to the timestamp value used in the last writer operation (used in a register, unregister, dispose, or write, with either the automatically supplied timestamp or the application provided timestamp). This timestamp may potentially affect the order in which readers observe events from multiple writers. This timestamp will be available to the DDS_DataReader objects by means of the source_timestamp attribute inside the DDS_SampleInfo. Cannot be NULL.

Returns:: For keyed data type, a handle that can be used in the calls that take a DDS_InstanceHandle_t, such as write, dispose, unregister_instance, or return DDS_HANDLE_NIL on failure. If the instance_data is of a data type that has no keys, this function always return DDS_HANDLE_NIL.

See also:: DDS_DataWriter_unregister_instance

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

<<cert>> Reverses the action of DDS_DataWriter_register_instance.This operation is useful only for keyed data types. Using it for non-keyed types causes no effect and reports no error. The operation takes as a parameter an instance (of which only the key value is examined) and a handle.

This operation should only be called on an instance that is currently registered. This includes instances that have been auto-registered by calling operations such as write or dispose as described in DDS_DataWriter_register_instance. Otherwise, this operation may fail with DDS_RETCODE_BAD_PARAMETER.

This only need be called just once per instance, regardless of how many times register_instance was called for that instance.

When this operation is used, RTI Connext Micro will automatically supply the value of the source_timestamp that is used.

This operation informs RTI Connext Micro that the DDS_DataWriter is no longer going to provide any information about the instance. This operation also indicates that RTI Connext Micro can locally remove all information regarding that instance. The application should not attempt to use the handle previously allocated to that instance after calling DDS_DataWriter_unregister_instance().

The special value DDS_HANDLE_NIL can be used for the parameter handle. This indicates that the identity of the instance should be automatically deduced from the instance_data (by means of the key).

If handle is any value other than DDS_HANDLE_NIL, then it must correspond to an instance that has been registered. If there is no correspondence, the operation will fail with DDS_RETCODE_BAD_PARAMETER.

RTI Connext Micro will not detect the error when the handle is any value other than DDS_HANDLE_NIL, corresponds to an instance that has been registered, but does not correspond to the instance deduced from the instance_data (by means of the key). RTI Connext Micro will treat as if the unregister_instance() operation is for the instance as indicated by the handle.

If after a DDS_DataWriter_unregister_instance, the application wants to modify (DDS_DataWriter_write or DDS_DataWriter_dispose) an instance, it has to register it again, or else use the special handle value DDS_HANDLE_NIL.

This operation does not indicate that the instance is deleted (that is the purpose of DDS_DataWriter_dispose). The operation DDS_DataWriter_unregister_instance just indicates that the DDS_DataWriter no longer has anything to say about the instance. DDS_DataReader entities that are reading the instance may receive a sample with DDS_NOT_ALIVE_NO_WRITERS_INSTANCE_STATE for the instance, unless there are other DDS_DataWriter objects writing that same instance.

This operation can affect the ownership of the data instance (see OWNERSHIP). If the DDS_DataWriter was the exclusive owner of the instance, then calling unregister_instance() will relinquish that ownership.

Parameters:

instance_data <<in>> The instance that should be unregistered. If the data has a key and instance_handle is DDS_HANDLE_NIL, only the fields that represent the key are examined by the function. Otherwise, instance_data is not used. If instance_data is used, it must represent an instance that has been registerd. Otherwise, this method may fail with DDS_RETCODE_BAD_PARAMETER . If the data has a key, instance_data can be NULL only if handle is not DDS_HANDLE_NIL. Otherwise, this method will fail with DDS_RETCODE_BAD_PARAMETER.

handle <<in>> represents the instance to be unregistered. If the data has a key and handle is DDS_HANDLE_NIL, handle is not used and instance is deduced from instance_data. If the data has no key, handle is not used. If handle is used, it must represent an instance that has been registered. Otherwise, this method may fail with DDS_RETCODE_BAD_PARAMETER. This method will fail with DDS_RETCODE_BAD_PARAMETER if handle is NULL. If the data has a key, handle cannot be DDS_HANDLE_NIL if instance_data is NULL. Otherwise, this method will report the error DDS_RETCODE_BAD_PARAMETER.

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

See also:: DDS_DataWriter_register_instance

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

<<cert>> Performs the same function as DDS_DataWriter_unregister_instance except that it also provides the value for the source_timestamp.Explicitly provides the timestamp that will be available to the DDS_DataReader objects by means of the source_timestamp attribute inside the DDS_SampleInfo. (Refer to DDS_SampleInfo for details)

The constraints on the values of the parameters and the corresponding error behavior are the same specified for the DDS_DataWriter_unregister_instance operation.

Parameters:

instance_data <<in>> The instance that should be unregistered. If the data has a key and instance_handle is DDS_HANDLE_NIL, only the fields that represent the key are examined by the function. Otherwise, instance_data is not used. If instance_data is used, it must represent an instance that has been registerd. Otherwise, this method may fail with DDS_RETCODE_BAD_PARAMETER . If the data has a key, instance_data can be NULL only if handle is not DDS_HANDLE_NIL. Otherwise, this method will fail with DDS_RETCODE_BAD_PARAMETER.

handle <<in>> represents the instance to be unregistered. If the data has a key and handle is DDS_HANDLE_NIL, handle is not used and instance is deduced from instance_data. If the data has no key, handle is not used. If handle is used, it must represent an instance that has been registered. Otherwise, this method may fail with DDS_RETCODE_BAD_PARAMETER. This method will fail with DDS_RETCODE_BAD_PARAMETER if handle is NULL. If the data has a key, handle cannot be DDS_HANDLE_NIL if instance_data is NULL. Otherwise, this method will report the error DDS_RETCODE_BAD_PARAMETER.

Parameters:

source_timestamp <<in>> The timestamp value must be greater than or equal to the timestamp value used in the last writer operation (used in a register, unregister, dispose, or write, with either the automatically supplied timestamp or the application provided timestamp). This timestamp may potentially affect the order in which readers observe events from multiple writers. This timestamp will be available to the DDS_DataReader objects by means of the source_timestamp attribute inside the DDS_SampleInfo. Cannot be NULL.

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

See also:: DDS_DataWriter_register_instance

DDS_ReturnCode_t DDS_DataWriter_dispose	(	DDS_DataWriter *	self,
		const void *	instance_data,
		const DDS_InstanceHandle_t *	handle
	)

<<cert>> Requests the middleware to delete the data.

This operation is useful only for keyed data types. Using it for non-keyed types has no effect and reports no error.

The actual deletion is postponed until there is no more use for that data in the whole system.

Applications are made aware of the deletion by means of operations on the DDS_DataReader objects that already knew that instance. DDS_DataReader objects that didn't know the instance will never see it.

This operation does not modify the value of the instance. The instance_data parameter is passed just for the purposes of identifying the instance.

When this operation is used, RTI Connext Micro will automatically supply the value of the source_timestamp that is made available to DDS_DataReader objects by means of the source_timestamp attribute inside the DDS_SampleInfo.

The constraints on the values of the handle parameter and the corresponding error behavior are the same specified for the DDS_DataWriter_unregister_instance operation.

The special value DDS_HANDLE_NIL can be used for the parameter instance_handle. This indicates the identity of the instance should be automatically deduced from the instance_data (by means of the key).

If handle is any value other than DDS_HANDLE_NIL, then it must correspond to an instance that has been registered. If there is no correspondence, the operation will fail with DDS_RETCODE_BAD_PARAMETER.

RTI Connext Micro will not detect the error when the handle is any value other than DDS_HANDLE_NIL, corresponds to an instance that has been registered, but does not correspond to the instance deduced from the instance_data (by means of the key). RTI Connext Micro will treat as if the dispose() operation is for the instance as indicated by the handle.

This operation may block and time out (DDS_RETCODE_TIMEOUT) under the same circumtances described for DDS_DataWriter_write().

If there are no instance resources left, this operation may fail with DDS_RETCODE_OUT_OF_RESOURCES. Calling DDS_DataWriter_unregister_instance may help freeing up some resources.

Parameters:

instance_data <<in>> The data to dispose. If the data has a key and instance_handle is DDS_HANDLE_NIL, only the fields that represent the key are examined by the function. Otherwise, instance_data is not used. If the data has a key, instance_data can be NULL only if instance_handle is not DDS_HANDLE_NIL. Otherwise, this method will fail with DDS_RETCODE_BAD_PARAMETER.

handle <<in>> Either the handle returned by a previous call to DDS_DataWriter_register_instance, or else the special value DDS_HANDLE_NIL. If the data has a key and instance_handle is DDS_HANDLE_NIL, instance_handle is not used and instance is deduced from instance_data. If the data has no key, instance_handle is not used. If handle is used, it must represent a registered instance of type the matching data type. Otherwise, this method fail with DDS_RETCODE_BAD_PARAMETER. This method will fail with DDS_RETCODE_BAD_PARAMETER if handle is NULL. If the data has a key, instance_handle cannot be DDS_HANDLE_NIL if instance_data is NULL. Otherwise, this method will fail with DDS_RETCODE_BAD_PARAMETER.

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

DDS_ReturnCode_t DDS_DataWriter_dispose_w_timestamp	(	DDS_DataWriter *	self,
		const void *	instance_data,
		const DDS_InstanceHandle_t *	handle,
		const struct DDS_Time_t *	source_timestamp
	)

<<cert>> Performs the same function as DDS_DataWriter_dispose except that it also provides the value for the source_timestamp.

Explicitly provides the timestamp that will be available to the DDS_DataReader objects by means of the source_timestamp attribute inside the DDS_SampleInfo. (Refer to DDS_SampleInfo for details)

The constraints on the values of the parameters and the corresponding error behavior are the same specified for the DDS_DataWriter_dispose operation.

Parameters:

instance_data	<<in>> The data to dispose. If the data has a key and `instance_handle` is DDS_HANDLE_NIL, only the fields that represent the key are examined by the function. Otherwise, `instance_data` is not used. If the data has a key, `instance_data` can be NULL only if `instance_handle` is not DDS_HANDLE_NIL. Otherwise, this method will fail with DDS_RETCODE_BAD_PARAMETER.
handle	<<in>> Either the handle returned by a previous call to DDS_DataWriter_register_instance, or else the special value DDS_HANDLE_NIL. If the data has a key and `instance_handle` is DDS_HANDLE_NIL, `instance_handle` is not used and `instance` is deduced from `instance_data`. If the data has no key, `instance_handle` is not used. If `handle` is used, it must represent a registered instance of type the matching data type. Otherwise, this method fail with DDS_RETCODE_BAD_PARAMETER. This method will fail with DDS_RETCODE_BAD_PARAMETER if `handle` is NULL. If the data has a key, `instance_handle` cannot be DDS_HANDLE_NIL if `instance_data` is NULL. Otherwise, this method will fail with DDS_RETCODE_BAD_PARAMETER.
source_timestamp	<<in>> The timestamp value must be greater than or equal to the timestamp value used in the last writer operation (used in a register, unregister, dispose, or write, with either the automatically supplied timestamp or the application provided timestamp). This timestamp may potentially affect the order in which readers observe events from multiple writers. This timestamp will be available to the DDS_DataReader objects by means of the `source_timestamp` attribute inside the DDS_SampleInfo. Cannot be NULL.

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

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

<<cert>> Modifies the value of a data instance.

When this operation is used, RTI Connext Micro will automatically supply the value of the source_timestamp that is made available to DDS_DataReader objects by means of the source_timestamp attribute inside the DDS_SampleInfo. (Refer to DDS_SampleInfo for details).

As a side effect, this operation asserts liveliness on the DDS_DataWriter itself, the DDS_Publisher and the DDS_DomainParticipant.

Note that the special value DDS_HANDLE_NIL can be used for the parameter handle. This indicates the identity of the instance should be automatically deduced from the instance_data (by means of the key).

If handle is any value other than DDS_HANDLE_NIL, then it must correspond to an instance that has been registered. If there is no correspondence, the operation will fail with DDS_RETCODE_BAD_PARAMETER.

RTI Connext Micro will not detect the error when the handle is any value other than DDS_HANDLE_NIL, corresponds to an instance that has been registered, but does not correspond to the instance deduced from the instance_data (by means of the key). RTI Connext Micro will treat as if the write() operation is for the instance as indicated by the handle.

If there are no instance resources left, this operation may fail with DDS_RETCODE_OUT_OF_RESOURCES. Calling DDS_DataWriter_unregister_instance may help freeing up some resources.

Parameters:

instance_data	<<in>> The data to write. This method will fail with DDS_RETCODE_BAD_PARAMETER if `instance_data` is NULL.
handle	<<in>> Either the handle returned by a previous call to DDS_DataWriter_register_instance, or else the special value DDS_HANDLE_NIL. If the data has a key and `handle` is not DDS_HANDLE_NIL, `handle` must represent a registered instance of the data. Otherwise, this method may fail with DDS_RETCODE_BAD_PARAMETER. This method will fail with DDS_RETCODE_BAD_PARAMETER if `handle` is NULL.

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

See also:: DDS_DataReader; DDS_DataWriter_write_w_timestamp

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

<<cert>> Performs the same function as DDS_DataWriter_write except that it also provides the value for the source_timestamp.Explicitly provides the timestamp that will be available to the DDS_DataReader objects by means of the source_timestamp attribute inside the DDS_SampleInfo. (Refer to DDS_SampleInfo for details)

The constraints on the values of the handle parameter and the corresponding error behavior are the same specified for the DDS_DataWriter_write operation.

If there are no instance resources left, this operation may fail with DDS_RETCODE_OUT_OF_RESOURCES. Calling DDS_DataWriter_unregister_instance may help free up some resources.

This operation may fail with DDS_RETCODE_BAD_PARAMETER under the same circumstances described for the write operation.

Parameters:

instance_data	<<in>> The data to write. This method will fail with DDS_RETCODE_BAD_PARAMETER if `instance_data` is NULL.
handle	<<in>> Either the handle returned by a previous call to DDS_DataWriter_register_instance, or else the special value DDS_HANDLE_NIL. If the data has a key and `handle` is not DDS_HANDLE_NIL, `handle` must represent a registered instance of the matching data type. Otherwise, this method may fail with DDS_RETCODE_BAD_PARAMETER. This method will fail with DDS_RETCODE_BAD_PARAMETER if `handle` is NULL.
source_timestamp	<<in>> The timestamp value must be greater than or equal to the timestamp value used in the last writer operation (used in a register, unregister, dispose, or write, with either the automatically supplied timestamp or the application provided timestamp). This timestamp may potentially affect the order in which readers observe events from multiple writers. This timestamp will be available to the DDS_DataReader objects by means of the `source_timestamp` attribute inside the DDS_SampleInfo. Cannot be NULL.

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

See also:: DDS_DataWriter_write; DDS_DataReader

DDS_ReturnCode_t DDS_DataWriter_write_w_params	(	DDS_DataWriter *	self,
		const void *	instance_data,
		struct DDS_WriteParams_t *	params
	)

Publish a data sample using the given set of additional parameters.

Parameters:

instance_data	<<in>>. Data sample to be published.
params	<<in>>. Additional parameters controlling the publishing of the sample.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation