RTI Connext C API Version 7.1.0

DDS_DataWriter entity and associated elements More...

Data Structures

struct  FooDataWriter
 <<interface>> <<generic>> User data type specific data writer. More...
 
struct  DDS_OfferedDeadlineMissedStatus
 DDS_OFFERED_DEADLINE_MISSED_STATUS More...
 
struct  DDS_LivelinessLostStatus
 DDS_LIVELINESS_LOST_STATUS More...
 
struct  DDS_OfferedIncompatibleQosStatus
 DDS_OFFERED_INCOMPATIBLE_QOS_STATUS More...
 
struct  DDS_PublicationMatchedStatus
 DDS_PUBLICATION_MATCHED_STATUS More...
 
struct  DDS_ServiceRequestAcceptedStatus
 DDS_SERVICE_REQUEST_ACCEPTED_STATUS More...
 
struct  DDS_ReliableWriterCacheEventCount
 <<extension>> The number of times the number of unacknowledged samples in the cache of a reliable writer hit a certain well-defined threshold. More...
 
struct  DDS_ReliableWriterCacheChangedStatus
 <<extension>> A summary of the state of a data writer's cache of unacknowledged samples written. More...
 
struct  DDS_ReliableReaderActivityChangedStatus
 <<extension>> Describes the activity (i.e. are acknowledgements forthcoming) of reliable readers matched to a reliable writer. More...
 
struct  DDS_DataWriterCacheStatus
 <<extension>> The status of the DataWriter's cache. Provides information on cache related metrics such as the number of samples and instances in the DataWriter queue. More...
 
struct  DDS_DataWriterProtocolStatus
 <<extension>> The status of a writer's internal protocol related metrics, like the number of samples pushed, pulled, filtered; and status of wire protocol traffic. More...
 
struct  DDS_AcknowledgmentInfo
 Information about an application-level acknowledged sample. More...
 
struct  DDS_DataWriterQos
 QoS policies supported by a DDS_DataWriter entity. More...
 
struct  DDS_DataWriterListener
 <<interface>> DDS_Listener for writer status. More...
 

Macros

#define DDS_OfferedDeadlineMissedStatus_INITIALIZER
 Initializer for new status instances. More...
 
#define DDS_LivelinessLostStatus_INITIALIZER
 Initializer for new status instances. More...
 
#define DDS_OfferedIncompatibleQosStatus_INITIALIZER
 Initializer for new status instances. More...
 
#define DDS_PublicationMatchedStatus_INITIALIZER
 Initializer for new status instances. More...
 
#define DDS_ServiceRequestAcceptedStatus_INITIALIZER
 Initializer for new status instances. More...
 
#define DDS_ReliableWriterCacheChangedStatus_INITIALIZER
 Initializer for new status instances. More...
 
#define DDS_ReliableReaderActivityChangedStatus_INITIALIZER
 Initializer for new status instances. More...
 
#define DDS_DataWriterCacheStatus_INITIALIZER
 Initializer for new status instances. More...
 
#define DDS_DataWriterProtocolStatus_INITIALIZER
 Initializer for new status instances. More...
 
#define DDS_DataWriterQos_INITIALIZER
 Initializer for new QoS instances. More...
 
#define DDS_DataWriterListener_INITIALIZER
 Initializer for new DDS_DataWriterListener. More...
 

Typedefs

typedef struct DDS_DataWriterImpl DDS_DataWriter
 <<interface>> Allows an application to set the value of the data to be published under a given DDS_Topic. More...
 
typedef void(* DDS_DataWriterListener_OfferedDeadlineMissedCallback) (void *listener_data, DDS_DataWriter *writer, const struct DDS_OfferedDeadlineMissedStatus *status)
 Prototype of a DDS_DataWriterListener on_offered_deadline_missed function. More...
 
typedef void(* DDS_DataWriterListener_LivelinessLostCallback) (void *listener_data, DDS_DataWriter *writer, const struct DDS_LivelinessLostStatus *status)
 Prototype of a DDS_DataWriterListener on_liveliness_lost function. More...
 
typedef void(* DDS_DataWriterListener_OfferedIncompatibleQosCallback) (void *listener_data, DDS_DataWriter *writer, const struct DDS_OfferedIncompatibleQosStatus *status)
 Prototype of a DDS_DataWriterListener on_offered_incompatible_qos function. More...
 
typedef void(* DDS_DataWriterListener_PublicationMatchedCallback) (void *listener_data, DDS_DataWriter *writer, const struct DDS_PublicationMatchedStatus *status)
 Prototype of a DDS_DataWriterListener on_publication_matched function. More...
 
typedef void(* DDS_DataWriterListener_ReliableWriterCacheChangedCallback) (void *listener_data, DDS_DataWriter *writer, const struct DDS_ReliableWriterCacheChangedStatus *status)
 <<extension>> A change has occurred in the writer's cache. More...
 
typedef void(* DDS_DataWriterListener_ReliableReaderActivityChangedCallback) (void *listener_data, DDS_DataWriter *writer, const struct DDS_ReliableReaderActivityChangedStatus *status)
 <<extension>> A matched reliable reader has become active or become inactive. More...
 
typedef void(* DDS_DataWriterListener_SampleRemovedCallback) (void *listener_data, DDS_DataWriter *writer, const struct DDS_Cookie_t *cookie)
 <<extension>> A sample has been removed from the DataWriter's queue. More...
 
typedef void(* DDS_DataWriterListener_InstanceReplacedCallback) (void *listener_data, DDS_DataWriter *writer, const DDS_InstanceHandle_t *handle)
 <<extension>> An instance previously registered with the writer has been replaced More...
 
typedef void(* DDS_DataWriterListener_OnApplicationAcknowledgmentCallback) (void *listener_data, DDS_DataWriter *writer, const struct DDS_AcknowledgmentInfo *info)
 <<extension>> An application-level acknowledgment has been received for a sample More...
 
typedef void(* DDS_DataWriterListener_ServiceRequestAcceptedCallback) (void *listener_data, DDS_DataWriter *writer, const struct DDS_ServiceRequestAcceptedStatus *status)
 <<extension>> a DDS_ServiceRequest for the DDS_TopicQuery service is dispatched to this DDS_DataWriter. More...
 

Functions

FooDataWriterFooDataWriter_narrow (DDS_DataWriter *writer)
 Narrow the given DDS_DataWriter pointer to a FooDataWriter pointer. More...
 
DDS_DataWriterFooDataWriter_as_datawriter (FooDataWriter *writer)
 Widen the given FooDataWriter pointer to a DDS_DataWriter pointer. More...
 
DDS_InstanceHandle_t FooDataWriter_register_instance (FooDataWriter *self, const Foo *instance_data)
 Informs RTI Connext that the application will be modifying a particular instance. More...
 
DDS_InstanceHandle_t FooDataWriter_register_instance_w_timestamp (FooDataWriter *self, const Foo *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. More...
 
DDS_InstanceHandle_t FooDataWriter_register_instance_w_params (FooDataWriter *self, const Foo *instance_data, struct DDS_WriteParams_t *params)
 Performs the same function as FooDataWriter_register_instance and FooDataWriter_register_instance_w_timestamp except that it also provides the values contained in params. More...
 
DDS_ReturnCode_t FooDataWriter_unregister_instance (FooDataWriter *self, const Foo *instance_data, const DDS_InstanceHandle_t *handle)
 Reverses the action of FooDataWriter_register_instance. More...
 
DDS_ReturnCode_t FooDataWriter_unregister_instance_w_timestamp (FooDataWriter *self, const Foo *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. More...
 
DDS_ReturnCode_t FooDataWriter_unregister_instance_w_params (FooDataWriter *self, const Foo *instance_data, struct DDS_WriteParams_t *params)
 Performs the same function as FooDataWriter_unregister_instance and FooDataWriter_unregister_instance_w_timestamp except that it also provides the values contained in params. More...
 
DDS_ReturnCode_t FooDataWriter_write (FooDataWriter *self, const Foo *instance_data, const DDS_InstanceHandle_t *handle)
 Modifies the value of a data instance. More...
 
DDS_ReturnCode_t FooDataWriter_write_w_timestamp (FooDataWriter *self, const Foo *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. More...
 
DDS_ReturnCode_t FooDataWriter_write_w_params (FooDataWriter *self, const Foo *instance_data, struct DDS_WriteParams_t *params)
 Performs the same function as FooDataWriter_write and FooDataWriter_write_w_timestamp except that it also provides the values contained in params. More...
 
DDS_ReturnCode_t FooDataWriter_dispose (FooDataWriter *self, const Foo *instance_data, const DDS_InstanceHandle_t *instance_handle)
 Requests the middleware to delete the instance. More...
 
DDS_ReturnCode_t FooDataWriter_dispose_w_timestamp (FooDataWriter *self, const Foo *instance_data, const DDS_InstanceHandle_t *instance_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. More...
 
DDS_ReturnCode_t FooDataWriter_dispose_w_params (FooDataWriter *self, const Foo *instance_data, struct DDS_WriteParams_t *params)
 Performs the same function as FooDataWriter_dispose and FooDataWriter_dispose_w_timestamp except that it also provides the values contained in params. More...
 
DDS_ReturnCode_t FooDataWriter_get_key_value (FooDataWriter *self, Foo *key_holder, const DDS_InstanceHandle_t *handle)
 Retrieve the instance key that corresponds to an instance handle. More...
 
DDS_InstanceHandle_t FooDataWriter_lookup_instance (FooDataWriter *self, const Foo *key_holder)
 Retrieve the instance handle that corresponds to an instance key_holder. More...
 
void * FooDataWriter_create_data (FooDataWriter *self)
 Creates a data sample and initializes it. More...
 
void * FooDataWriter_create_data_w_params (FooDataWriter *self, const struct DDS_TypeAllocationParams_t *alloc_params)
 Creates a data sample and initializes it. More...
 
DDS_Boolean FooDataWriter_delete_data (FooDataWriter *self, Foo *sample)
 Destroys a user data type instance. More...
 
void * FooDataWriter_delete_data_w_params (FooDataWriter *self, Foo *sample, const struct DDS_TypeDeallocationParams_t *dealloc_params)
 Destroys a user data type instance. More...
 
DDS_ReturnCode_t FooDataWriter_get_loan (FooDataWriter *self, Foo **sample)
 Gets a sample managed by the DataWriter. More...
 
DDS_ReturnCode_t FooDataWriter_discard_loan (FooDataWriter *self, Foo *sample)
 Returns a loaned sample back to the DataWriter. More...
 
DDS_ReturnCode_t DDS_OfferedDeadlineMissedStatus_initialize (struct DDS_OfferedDeadlineMissedStatus *self)
 Initializer for new status instances. More...
 
DDS_ReturnCode_t DDS_OfferedDeadlineMissedStatus_copy (struct DDS_OfferedDeadlineMissedStatus *self, const struct DDS_OfferedDeadlineMissedStatus *source)
 Copy the contents of the given status into this status. More...
 
DDS_ReturnCode_t DDS_OfferedDeadlineMissedStatus_finalize (struct DDS_OfferedDeadlineMissedStatus *self)
 Free any dynamic memory allocated by status instances. More...
 
DDS_ReturnCode_t DDS_LivelinessLostStatus_initialize (struct DDS_LivelinessLostStatus *self)
 Initializer for new status instances. More...
 
DDS_ReturnCode_t DDS_LivelinessLostStatus_copy (struct DDS_LivelinessLostStatus *self, const struct DDS_LivelinessLostStatus *source)
 Copy the contents of the given status into this status. More...
 
DDS_ReturnCode_t DDS_LivelinessLostStatus_finalize (struct DDS_LivelinessLostStatus *self)
 Free any dynamic memory allocated by status instances. More...
 
DDS_ReturnCode_t DDS_OfferedIncompatibleQosStatus_initialize (struct DDS_OfferedIncompatibleQosStatus *self)
 Initializer for new status instances. More...
 
DDS_ReturnCode_t DDS_OfferedIncompatibleQosStatus_copy (struct DDS_OfferedIncompatibleQosStatus *self, const struct DDS_OfferedIncompatibleQosStatus *source)
 Copy the contents of the given status into this status. More...
 
DDS_ReturnCode_t DDS_OfferedIncompatibleQosStatus_finalize (struct DDS_OfferedIncompatibleQosStatus *self)
 Free any dynamic memory allocated by status instances. More...
 
DDS_ReturnCode_t DDS_PublicationMatchedStatus_initialize (struct DDS_PublicationMatchedStatus *self)
 Initializer for new status instances. More...
 
DDS_ReturnCode_t DDS_PublicationMatchedStatus_copy (struct DDS_PublicationMatchedStatus *self, const struct DDS_PublicationMatchedStatus *source)
 Copy the contents of the given status into this status. More...
 
DDS_ReturnCode_t DDS_PublicationMatchedStatus_finalize (struct DDS_PublicationMatchedStatus *self)
 Free any dynamic memory allocated by status instances. More...
 
DDS_ReturnCode_t DDS_ServiceRequestAcceptedStatus_initialize (struct DDS_ServiceRequestAcceptedStatus *self)
 Initializer for new status instances. More...
 
DDS_ReturnCode_t DDS_ServiceRequestAcceptedStatus_copy (struct DDS_ServiceRequestAcceptedStatus *self, const struct DDS_ServiceRequestAcceptedStatus *source)
 Copy the contents of the given status into this status. More...
 
DDS_ReturnCode_t DDS_ServiceRequestAcceptedStatus_finalize (struct DDS_ServiceRequestAcceptedStatus *self)
 Free any dynamic memory allocated by status instances. More...
 
DDS_ReturnCode_t DDS_ReliableWriterCacheChangedStatus_initialize (struct DDS_ReliableWriterCacheChangedStatus *self)
 Initializer for new status instances. More...
 
DDS_ReturnCode_t DDS_ReliableWriterCacheChangedStatus_copy (struct DDS_ReliableWriterCacheChangedStatus *self, const struct DDS_ReliableWriterCacheChangedStatus *source)
 Copy the contents of the given status into this status. More...
 
DDS_ReturnCode_t DDS_ReliableWriterCacheChangedStatus_finalize (struct DDS_ReliableWriterCacheChangedStatus *self)
 Free any dynamic memory allocated by status instances. More...
 
DDS_ReturnCode_t DDS_ReliableReaderActivityChangedStatus_initialize (struct DDS_ReliableReaderActivityChangedStatus *self)
 Initializer for new status instances. More...
 
DDS_ReturnCode_t DDS_ReliableReaderActivityChangedStatus_copy (struct DDS_ReliableReaderActivityChangedStatus *self, const struct DDS_ReliableReaderActivityChangedStatus *source)
 Copy the contents of the given status into this status. More...
 
DDS_ReturnCode_t DDS_ReliableReaderActivityChangedStatus_finalize (struct DDS_ReliableReaderActivityChangedStatus *self)
 Free any dynamic memory allocated by status instances. More...
 
DDS_ReturnCode_t DDS_DataWriterCacheStatus_initialize (struct DDS_DataWriterCacheStatus *self)
 Initializer for new status instances. More...
 
DDS_ReturnCode_t DDS_DataWriterCacheStatus_copy (struct DDS_DataWriterCacheStatus *self, const struct DDS_DataWriterCacheStatus *source)
 Copy the contents of the given status into this status. More...
 
DDS_ReturnCode_t DDS_DataWriterCacheStatus_finalize (struct DDS_DataWriterCacheStatus *self)
 Free any dynamic memory allocated by status instances. More...
 
DDS_ReturnCode_t DDS_DataWriterProtocolStatus_initialize (struct DDS_DataWriterProtocolStatus *self)
 Initializer for new status instances. More...
 
DDS_ReturnCode_t DDS_DataWriterProtocolStatus_copy (struct DDS_DataWriterProtocolStatus *self, const struct DDS_DataWriterProtocolStatus *source)
 Copy the contents of the given status into this status. More...
 
DDS_ReturnCode_t DDS_DataWriterProtocolStatus_finalize (struct DDS_DataWriterProtocolStatus *self)
 Free any dynamic memory allocated by status instances. More...
 
DDS_Boolean DDS_DataWriterQos_equals (const struct DDS_DataWriterQos *self, const struct DDS_DataWriterQos *other)
 Compares two DDS_DataWriterQos for equality. More...
 
DDS_ReturnCode_t DDS_DataWriterQos_print (const struct DDS_DataWriterQos *self)
 Prints this DDS_DataWriterQos to stdout. More...
 
DDS_ReturnCode_t DDS_DataWriterQos_to_string (const struct DDS_DataWriterQos *self, char *string, DDS_UnsignedLong *string_size)
 Obtains a string representation of this DDS_DataWriterQos. More...
 
DDS_ReturnCode_t DDS_DataWriterQos_to_string_w_params (const struct DDS_DataWriterQos *self, char *string, DDS_UnsignedLong *string_size, const struct DDS_DataWriterQos *base, const struct DDS_QosPrintFormat *format)
 Obtains a string representation of this DDS_DataWriterQos. More...
 
DDS_ReturnCode_t DDS_DataWriterQos_initialize (struct DDS_DataWriterQos *self)
 Initializer for new QoS instances. More...
 
DDS_ReturnCode_t DDS_DataWriterQos_finalize (struct DDS_DataWriterQos *self)
 Free any dynamic memory allocated by the policies in this DDS_DataWriterQos. More...
 
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. More...
 
DDS_EntityDDS_DataWriter_as_entity (DDS_DataWriter *dataWriter)
 Access a DDS_DataWriter's supertype instance. More...
 
DDS_ReturnCode_t DDS_DataWriter_assert_liveliness (DDS_DataWriter *self)
 This operation manually asserts the liveliness of this DDS_DataWriter. More...
 
DDS_ReturnCode_t DDS_DataWriter_get_matched_subscription_locators (DDS_DataWriter *self, struct DDS_LocatorSeq *locators)
 <<extension>> Retrieve the list of locators for subscriptions currently "associated" with this DDS_DataWriter. More...
 
DDS_ReturnCode_t DDS_DataWriter_get_matched_subscriptions (DDS_DataWriter *self, struct DDS_InstanceHandleSeq *subscription_handles)
 Retrieve the list of subscriptions currently "associated" with this DDS_DataWriter. More...
 
DDS_ReturnCode_t DDS_DataWriter_is_matched_subscription_active (DDS_DataWriter *self, DDS_Boolean *is_active, const DDS_InstanceHandle_t *subscription_handle)
 Check if a subscription currently matched with a DataWriter is active. More...
 
DDS_ReturnCode_t DDS_DataWriter_get_matched_subscription_data (DDS_DataWriter *self, struct DDS_SubscriptionBuiltinTopicData *subscription_data, const DDS_InstanceHandle_t *subscription_handle)
 This operation retrieves the information on a subscription that is currently "associated" with the DDS_DataWriter. More...
 
DDS_ReturnCode_t DDS_DataWriter_get_matched_subscription_participant_data (DDS_DataWriter *self, struct DDS_ParticipantBuiltinTopicData *participant_data, const DDS_InstanceHandle_t *subscription_handle)
 This operation retrieves the information on the discovered DDS_DomainParticipant associated with the subscription that is currently matching with the DDS_DataWriter. More...
 
DDS_TopicDDS_DataWriter_get_topic (DDS_DataWriter *self)
 This operation returns the DDS_Topic associated with the DDS_DataWriter. More...
 
DDS_PublisherDDS_DataWriter_get_publisher (DDS_DataWriter *self)
 This operation returns the DDS_Publisher to which the DDS_DataWriter belongs. More...
 
DDS_ReturnCode_t DDS_DataWriter_wait_for_acknowledgments (DDS_DataWriter *self, const struct DDS_Duration_t *max_wait)
 Blocks the calling thread until all data written by reliable DDS_DataWriter entity is acknowledged, or until timeout expires. More...
 
DDS_ReturnCode_t DDS_DataWriter_is_sample_app_acknowledged (DDS_DataWriter *self, DDS_Boolean *is_app_ack, const struct DDS_SampleIdentity_t *identity)
 This function can be used to see if a sample has been application acknowledged. More...
 
DDS_ReturnCode_t DDS_DataWriter_wait_for_asynchronous_publishing (DDS_DataWriter *self, const struct DDS_Duration_t *max_wait)
 <<extension>> Blocks the calling thread until asynchronous sending is complete. More...
 
DDS_ReturnCode_t DDS_DataWriter_get_liveliness_lost_status (DDS_DataWriter *self, struct DDS_LivelinessLostStatus *status)
 Accesses the DDS_LIVELINESS_LOST_STATUS communication status. More...
 
DDS_ReturnCode_t DDS_DataWriter_get_offered_deadline_missed_status (DDS_DataWriter *self, struct DDS_OfferedDeadlineMissedStatus *status)
 Accesses the DDS_OFFERED_DEADLINE_MISSED_STATUS communication status. More...
 
DDS_ReturnCode_t DDS_DataWriter_get_offered_incompatible_qos_status (DDS_DataWriter *self, struct DDS_OfferedIncompatibleQosStatus *status)
 Accesses the DDS_OFFERED_INCOMPATIBLE_QOS_STATUS communication status. More...
 
DDS_ReturnCode_t DDS_DataWriter_get_publication_matched_status (DDS_DataWriter *self, struct DDS_PublicationMatchedStatus *status)
 Accesses the DDS_PUBLICATION_MATCHED_STATUS communication status. More...
 
DDS_ReturnCode_t DDS_DataWriter_get_reliable_writer_cache_changed_status (DDS_DataWriter *self, struct DDS_ReliableWriterCacheChangedStatus *status)
 <<extension>> Get the reliable cache status for this writer. More...
 
DDS_ReturnCode_t DDS_DataWriter_get_reliable_reader_activity_changed_status (DDS_DataWriter *self, struct DDS_ReliableReaderActivityChangedStatus *status)
 <<extension>> Get the reliable reader activity changed status for this writer. More...
 
DDS_ReturnCode_t DDS_DataWriter_get_datawriter_cache_status (DDS_DataWriter *self, struct DDS_DataWriterCacheStatus *status)
 <<extension>> Get the datawriter cache status for this writer. More...
 
DDS_ReturnCode_t DDS_DataWriter_get_datawriter_protocol_status (DDS_DataWriter *self, struct DDS_DataWriterProtocolStatus *status)
 <<extension>> Get the datawriter protocol status for this writer. More...
 
DDS_ReturnCode_t DDS_DataWriter_get_matched_subscription_datawriter_protocol_status (DDS_DataWriter *self, struct DDS_DataWriterProtocolStatus *status, const DDS_InstanceHandle_t *subscription_handle)
 <<extension>> Get the datawriter protocol status for this writer, per matched subscription identified by the subscription_handle. More...
 
DDS_ReturnCode_t DDS_DataWriter_get_matched_subscription_datawriter_protocol_status_by_locator (DDS_DataWriter *self, struct DDS_DataWriterProtocolStatus *status, const struct DDS_Locator_t *locator)
 <<extension>> Get the datawriter protocol status for this writer, per matched subscription identified by the locator. More...
 
DDS_ReturnCode_t DDS_DataWriter_get_service_request_accepted_status (DDS_DataWriter *self, struct DDS_ServiceRequestAcceptedStatus *status)
 Accesses the DDS_SERVICE_REQUEST_ACCEPTED_STATUS communication status. More...
 
DDS_ReturnCode_t DDS_DataWriter_set_qos (DDS_DataWriter *self, const struct DDS_DataWriterQos *qos)
 Sets the writer QoS. More...
 
DDS_ReturnCode_t DDS_DataWriter_set_qos_with_profile (DDS_DataWriter *self, const char *library_name, const char *profile_name)
 <<extension>> Change the QoS of this writer using the input XML QoS profile. More...
 
DDS_ReturnCode_t DDS_DataWriter_get_qos (DDS_DataWriter *self, struct DDS_DataWriterQos *qos)
 Gets the writer QoS. More...
 
DDS_ReturnCode_t DDS_DataWriter_set_property (DDS_DataWriter *self, const char *property_name, const char *value, DDS_Boolean propagate)
 Set the value for a property that applies to a DataWriter. More...
 
DDS_ReturnCode_t DDS_DataWriter_set_listener (DDS_DataWriter *self, const struct DDS_DataWriterListener *l, DDS_StatusMask mask)
 Sets the writer listener. More...
 
struct DDS_DataWriterListener DDS_DataWriter_get_listener (DDS_DataWriter *self)
 Get the writer listener. More...
 
DDS_ReturnCode_t DDS_DataWriter_get_listenerX (DDS_DataWriter *self, struct DDS_DataWriterListener *listener)
 <<extension>> Get the writer listener. More...
 
DDS_ReturnCode_t DDS_DataWriter_flush (DDS_DataWriter *self)
 <<extension>> Flushes the batch in progress in the context of the calling thread. More...
 
DDS_ReturnCode_t DDS_DataWriter_take_discovery_snapshot (DDS_DataWriter *self, const char *file_name)
 Take a snapshot of the compatible and incompatible remote readers matched by a local writer. More...
 

Detailed Description

DDS_DataWriter entity and associated elements

Macro Definition Documentation

◆ DDS_OfferedDeadlineMissedStatus_INITIALIZER

#define DDS_OfferedDeadlineMissedStatus_INITIALIZER

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 function. 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. DDS_OfferedDeadlineMissedStatus_finalize should be called to free the contained fields that use dynamic memory:

DDS_ReturnCode_t DDS_OfferedDeadlineMissedStatus_finalize(struct DDS_OfferedDeadlineMissedStatus *self)
Free any dynamic memory allocated by status instances.
DDS_ReturnCode_t DDS_DataWriter_get_offered_deadline_missed_status(DDS_DataWriter *self, struct DDS_OfferedDeadlineMissedStatus *status)
Accesses the DDS_OFFERED_DEADLINE_MISSED_STATUS communication status.
#define DDS_OfferedDeadlineMissedStatus_INITIALIZER
Initializer for new status instances.
Definition: publication.ifc:222
DDS_OFFERED_DEADLINE_MISSED_STATUS
Definition: publication.ifc:205
See also
DDS_OfferedDeadlineMissedStatus_initialize
DDS_DataWriter_get_offered_deadline_missed_status
DDS_OfferedDeadlineMissedStatus_finalize

◆ DDS_LivelinessLostStatus_INITIALIZER

#define DDS_LivelinessLostStatus_INITIALIZER

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 function. 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. DDS_LivelinessLostStatus_finalize should be called to free the contained fields that use dynamic memory:

DDS_ReturnCode_t DDS_DataWriter_get_liveliness_lost_status(DDS_DataWriter *self, struct DDS_LivelinessLostStatus *status)
Accesses the DDS_LIVELINESS_LOST_STATUS communication status.
#define DDS_LivelinessLostStatus_INITIALIZER
Initializer for new status instances.
Definition: publication.ifc:260
DDS_ReturnCode_t DDS_LivelinessLostStatus_finalize(struct DDS_LivelinessLostStatus *self)
Free any dynamic memory allocated by status instances.
DDS_LIVELINESS_LOST_STATUS
Definition: publication.ifc:247
See also
DDS_LivelinessLostStatus_initialize
DDS_DataWriter_get_liveliness_lost_status
DDS_LivelinessLostStatus_finalize

◆ DDS_OfferedIncompatibleQosStatus_INITIALIZER

#define DDS_OfferedIncompatibleQosStatus_INITIALIZER

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 function. 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. DDS_OfferedIncompatibleQosStatus_finalize should be called to free the contained fields that use dynamic memory:

#define DDS_OfferedIncompatibleQosStatus_INITIALIZER
Initializer for new status instances.
Definition: publication.ifc:304
DDS_ReturnCode_t DDS_DataWriter_get_offered_incompatible_qos_status(DDS_DataWriter *self, struct DDS_OfferedIncompatibleQosStatus *status)
Accesses the DDS_OFFERED_INCOMPATIBLE_QOS_STATUS communication status.
DDS_ReturnCode_t DDS_OfferedIncompatibleQosStatus_finalize(struct DDS_OfferedIncompatibleQosStatus *self)
Free any dynamic memory allocated by status instances.
DDS_OFFERED_INCOMPATIBLE_QOS_STATUS
Definition: publication.ifc:283
See also
DDS_DataWriter_get_offered_incompatible_qos_status
DDS_OfferedIncompatibleQosStatus_finalize

◆ DDS_PublicationMatchedStatus_INITIALIZER

#define DDS_PublicationMatchedStatus_INITIALIZER

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 function. 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. DDS_PublicationMatchedStatus_finalize should be called to free the contained fields that use dynamic memory:

#define DDS_PublicationMatchedStatus_INITIALIZER
Initializer for new status instances.
Definition: publication.ifc:358
DDS_ReturnCode_t DDS_PublicationMatchedStatus_finalize(struct DDS_PublicationMatchedStatus *self)
Free any dynamic memory allocated by status instances.
DDS_ReturnCode_t DDS_DataWriter_get_publication_matched_status(DDS_DataWriter *self, struct DDS_PublicationMatchedStatus *status)
Accesses the DDS_PUBLICATION_MATCHED_STATUS communication status.
DDS_PUBLICATION_MATCHED_STATUS
Definition: publication.ifc:329
See also
DDS_DataWriter_get_publication_matched_status
DDS_PublicationMatchedStatus_finalize

◆ DDS_ServiceRequestAcceptedStatus_INITIALIZER

#define DDS_ServiceRequestAcceptedStatus_INITIALIZER

Initializer for new status instances.

New DDS_ServiceRequestAcceptedStatus instances stored on the stack should be initialized with this value before they are passed to any function. 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. DDS_ServiceRequestAcceptedStatus_finalize should be called to free the contained fields that use dynamic memory:

#define DDS_ServiceRequestAcceptedStatus_INITIALIZER
Initializer for new status instances.
Definition: publication.ifc:408
DDS_ReturnCode_t DDS_ServiceRequestAcceptedStatus_finalize(struct DDS_ServiceRequestAcceptedStatus *self)
Free any dynamic memory allocated by status instances.
DDS_ReturnCode_t DDS_DataWriter_get_service_request_accepted_status(DDS_DataWriter *self, struct DDS_ServiceRequestAcceptedStatus *status)
Accesses the DDS_SERVICE_REQUEST_ACCEPTED_STATUS communication status.
DDS_SERVICE_REQUEST_ACCEPTED_STATUS
Definition: publication.ifc:381
See also
DDS_DataWriter_get_service_request_accepted_status
DDS_ServiceRequestAcceptedStatus_finalize

◆ DDS_ReliableWriterCacheChangedStatus_INITIALIZER

#define DDS_ReliableWriterCacheChangedStatus_INITIALIZER

Initializer for new status instances.

New DDS_ReliableWriterCacheChangedStatus instances stored on the stack should be initialized with this value before they are passed to any function. 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. DDS_ReliableWriterCacheChangedStatus_finalize should be called to free the contained fields that use dynamic memory:

DDS_ReturnCode_t DDS_ReliableWriterCacheChangedStatus_finalize(struct DDS_ReliableWriterCacheChangedStatus *self)
Free any dynamic memory allocated by status instances.
#define DDS_ReliableWriterCacheChangedStatus_INITIALIZER
Initializer for new status instances.
Definition: publication.ifc:488
DDS_ReturnCode_t DDS_DataWriter_get_reliable_writer_cache_changed_status(DDS_DataWriter *self, struct DDS_ReliableWriterCacheChangedStatus *status)
<<extension>> Get the reliable cache status for this writer.
<<extension>> A summary of the state of a data writer's cache of unacknowledged samples written.
Definition: publication.ifc:453
See also
DDS_DataWriter_get_reliable_writer_cache_changed_status
DDS_ReliableWriterCacheChangedStatus_finalize

◆ DDS_ReliableReaderActivityChangedStatus_INITIALIZER

#define DDS_ReliableReaderActivityChangedStatus_INITIALIZER

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 function. 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. DDS_ReliableReaderActivityChangedStatus_finalize should be called to free the contained fields that use dynamic memory:

#define DDS_ReliableReaderActivityChangedStatus_INITIALIZER
Initializer for new status instances.
Definition: publication.ifc:545
DDS_ReturnCode_t DDS_DataWriter_get_reliable_reader_activity_changed_status(DDS_DataWriter *self, struct DDS_ReliableReaderActivityChangedStatus *status)
<<extension>> Get the reliable reader activity changed status for this writer.
DDS_ReturnCode_t DDS_ReliableReaderActivityChangedStatus_finalize(struct DDS_ReliableReaderActivityChangedStatus *self)
Free any dynamic memory allocated by status instances.
<<extension>> Describes the activity (i.e. are acknowledgements forthcoming) of reliable readers matc...
Definition: publication.ifc:520
See also
DDS_DataWriter_get_reliable_reader_activity_changed_status
DDS_ReliableReaderActivityChangedStatus_finalize

◆ DDS_DataWriterCacheStatus_INITIALIZER

#define DDS_DataWriterCacheStatus_INITIALIZER

Initializer for new status instances.

New DDS_DataWriterCacheStatus instances stored on the stack should be initialized with this value before they are passed to any function. 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. DDS_DataWriterCacheStatus_finalize should be called to free the contained fields that use dynamic memory:

DDS_ReturnCode_t DDS_DataWriterCacheStatus_finalize(struct DDS_DataWriterCacheStatus *self)
Free any dynamic memory allocated by status instances.
DDS_ReturnCode_t DDS_DataWriter_get_datawriter_cache_status(DDS_DataWriter *self, struct DDS_DataWriterCacheStatus *status)
<<extension>> Get the datawriter cache status for this writer.
#define DDS_DataWriterCacheStatus_INITIALIZER
Initializer for new status instances.
Definition: publication.ifc:598
<<extension>> The status of the DataWriter's cache. Provides information on cache related metrics suc...
Definition: publication.ifc:573
See also
DDS_DataWriter_get_datawriter_cache_status
DDS_DataWriterCacheStatus_finalize

◆ DDS_DataWriterProtocolStatus_INITIALIZER

#define DDS_DataWriterProtocolStatus_INITIALIZER

Initializer for new status instances.

New DDS_DataWriterProtocolStatus instances stored on the stack should be initialized with this value before they are passed to any function. 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. DDS_DataWriterProtocolStatus_finalize should be called to free the contained fields that use dynamic memory:

DDS_ReturnCode_t DDS_DataWriterProtocolStatus_finalize(struct DDS_DataWriterProtocolStatus *self)
Free any dynamic memory allocated by status instances.
#define DDS_DataWriterProtocolStatus_INITIALIZER
Initializer for new status instances.
Definition: publication.ifc:770
DDS_ReturnCode_t DDS_DataWriter_get_datawriter_protocol_status(DDS_DataWriter *self, struct DDS_DataWriterProtocolStatus *status)
<<extension>> Get the datawriter protocol status for this writer.
<<extension>> The status of a writer's internal protocol related metrics, like the number of samples ...
Definition: publication.ifc:627
See also
DDS_DataWriter_get_datawriter_protocol_status
DDS_DataWriterProtocolStatus_finalize

◆ DDS_DataWriterQos_INITIALIZER

#define DDS_DataWriterQos_INITIALIZER

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 function. 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:

#define DDS_DataWriterQos_INITIALIZER
Initializer for new QoS instances.
Definition: publication.ifc:1189
QoS policies supported by a DDS_DataWriter entity.
Definition: publication.ifc:921

Note that the above assignment is not a substitute for calling DDS_Publisher_get_default_datawriter_qos or DDS_DataWriter_get_qos; one of those should be called subsequently to setting the QoS of a new or existing entity. DDS_DataWriterQos_finalize should be called to free the contained QoS policies that use dynamic memory:

DDS_DataWriter_set_qos(myDataWriter, &myQos);
DDS_ReturnCode_t DDS_Publisher_get_default_datawriter_qos(DDS_Publisher *self, struct DDS_DataWriterQos *qos)
Copies the default DDS_DataWriterQos values into the provided DDS_DataWriterQos instance.
DDS_ReturnCode_t DDS_DataWriterQos_finalize(struct DDS_DataWriterQos *self)
Free any dynamic memory allocated by the policies in this DDS_DataWriterQos.
DDS_ReturnCode_t DDS_DataWriter_set_qos(DDS_DataWriter *self, const struct DDS_DataWriterQos *qos)
Sets the writer QoS.
See also
DDS_Publisher_get_default_datawriter_qos
DDS_DataWriterQos_finalize

◆ DDS_DataWriterListener_INITIALIZER

#define DDS_DataWriterListener_INITIALIZER

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.

/* initialize listener functions */
listener.on_offered_deadline_missed = ....;
DDS_DataWriter_set_listener(myDataWriter, &listener, mask);
DDS_ReturnCode_t DDS_DataWriter_set_listener(DDS_DataWriter *self, const struct DDS_DataWriterListener *l, DDS_StatusMask mask)
Sets the writer listener.
#define DDS_DataWriterListener_INITIALIZER
Initializer for new DDS_DataWriterListener.
Definition: publication.ifc:1682
<<interface>> DDS_Listener for writer status.
Definition: publication.ifc:1613
DDS_DataWriterListener_OfferedDeadlineMissedCallback on_offered_deadline_missed
Handles the DDS_OFFERED_DEADLINE_MISSED_STATUS status.
Definition: publication.ifc:1621
See also
DDS_DataWriter_set_listener
DDS_DataWriterListener

Typedef Documentation

◆ DDS_DataWriter

typedef struct DDS_DataWriterImpl DDS_DataWriter

<<interface>> 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;
DDS_RELIABLE_READER_ACTIVITY_CHANGED_STATUS, DDS_ReliableReaderActivityChangedStatus;
DDS_RELIABLE_WRITER_CACHE_CHANGED_STATUS, DDS_ReliableWriterCacheChangedStatus.
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 (see USER_DATA). 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.

See also
FooDataWriter
Operations Allowed in Listener Callbacks

◆ DDS_DataWriterListener_OfferedDeadlineMissedCallback

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

Prototype of a DDS_DataWriterListener on_offered_deadline_missed function.

◆ DDS_DataWriterListener_LivelinessLostCallback

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

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

◆ DDS_DataWriterListener_OfferedIncompatibleQosCallback

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

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

◆ DDS_DataWriterListener_PublicationMatchedCallback

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

Prototype of a DDS_DataWriterListener on_publication_matched function.

◆ DDS_DataWriterListener_ReliableWriterCacheChangedCallback

typedef void(* DDS_DataWriterListener_ReliableWriterCacheChangedCallback) (void *listener_data, DDS_DataWriter *writer, const struct DDS_ReliableWriterCacheChangedStatus *status)

<<extension>> A change has occurred in the writer's cache.

This callback is triggered when the cache becomes empty or full, or when the number of unacknowledged samples reaches a high or low watermark.

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 writer cache changed status of the locally created DDS_DataWriter

◆ DDS_DataWriterListener_ReliableReaderActivityChangedCallback

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

<<extension>> 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

◆ DDS_DataWriterListener_SampleRemovedCallback

typedef void(* DDS_DataWriterListener_SampleRemovedCallback) (void *listener_data, DDS_DataWriter *writer, const struct DDS_Cookie_t *cookie)

<<extension>> A sample has been removed from the DataWriter's queue.

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
cookie<<out>>
See also
FooDataWriter_get_loan

◆ DDS_DataWriterListener_InstanceReplacedCallback

typedef void(* DDS_DataWriterListener_InstanceReplacedCallback) (void *listener_data, DDS_DataWriter *writer, const DDS_InstanceHandle_t *handle)

<<extension>> An instance previously registered with the writer has been replaced

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
handle<<out>> Handle of the replaced instance

◆ DDS_DataWriterListener_OnApplicationAcknowledgmentCallback

typedef void(* DDS_DataWriterListener_OnApplicationAcknowledgmentCallback) (void *listener_data, DDS_DataWriter *writer, const struct DDS_AcknowledgmentInfo *info)

<<extension>> An application-level acknowledgment has been received for a sample

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
info<<out>> DDS_AcknowledgmentInfo of the acknowledged sample

◆ DDS_DataWriterListener_ServiceRequestAcceptedCallback

typedef void(* DDS_DataWriterListener_ServiceRequestAcceptedCallback) (void *listener_data, DDS_DataWriter *writer, const struct DDS_ServiceRequestAcceptedStatus *status)

<<extension>> a DDS_ServiceRequest for the DDS_TopicQuery service is dispatched to this DDS_DataWriter.

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 service request accepted status of locally created DDS_DataWriter
See also
Topic Queries

Function Documentation

◆ FooDataWriter_narrow()

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. Cannot be NULL.
Returns
FooDataWriter if writer is of type Foo. Return NULL otherwise.

◆ FooDataWriter_as_datawriter()

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. Cannot be NULL.
Returns
DDS_DataWriter.

◆ FooDataWriter_register_instance()

DDS_InstanceHandle_t FooDataWriter_register_instance ( FooDataWriter self,
const Foo instance_data 
)

Informs RTI Connext 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 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 parameter to the write or dispose operation and RTI Connext 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 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
self<<in>> Cannot be NULL.
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 returns DDS_HANDLE_NIL.
See also
FooDataWriter_unregister_instance, FooDataWriter_get_key_value, Relationship between registration, liveliness and ownership

◆ FooDataWriter_register_instance_w_timestamp()

DDS_InstanceHandle_t FooDataWriter_register_instance_w_timestamp ( FooDataWriter self,
const Foo 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. Refer to DESTINATION_ORDER QoS policy for details.

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
self<<in>> Cannot be NULL.
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, FooDataWriter_get_key_value

◆ FooDataWriter_register_instance_w_params()

DDS_InstanceHandle_t FooDataWriter_register_instance_w_params ( FooDataWriter self,
const Foo instance_data,
struct DDS_WriteParams_t params 
)

Performs the same function as FooDataWriter_register_instance and FooDataWriter_register_instance_w_timestamp except that it also provides the values contained in params.

See also
FooDataWriter_write_w_params

◆ FooDataWriter_unregister_instance()

DDS_ReturnCode_t FooDataWriter_unregister_instance ( FooDataWriter self,
const Foo 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 will automatically supply the value of the source_timestamp that is used.

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

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

DDS_WriterDataLifecycleQosPolicy::autodispose_unregistered_instances controls whether instances are automatically disposed when they are unregistered.

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 function 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 function 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 function 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 function may fail with DDS_RETCODE_BAD_PARAMETER. This function 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 function will report the error DDS_RETCODE_BAD_PARAMETER.
self<<in>> 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_w_timestamp
FooDataWriter_get_key_value
Relationship between registration, liveliness and ownership

◆ FooDataWriter_unregister_instance_w_timestamp()

DDS_ReturnCode_t FooDataWriter_unregister_instance_w_timestamp ( FooDataWriter self,
const Foo 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. Refer to DESTINATION_ORDER QoS policy for details.

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
self<<in>> Cannot be NULL.
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 function 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 function 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 function may fail with DDS_RETCODE_BAD_PARAMETER. This function 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 function will report the error 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
FooDataWriter_get_key_value

◆ FooDataWriter_unregister_instance_w_params()

DDS_ReturnCode_t FooDataWriter_unregister_instance_w_params ( FooDataWriter self,
const Foo instance_data,
struct DDS_WriteParams_t params 
)

Performs the same function as FooDataWriter_unregister_instance and FooDataWriter_unregister_instance_w_timestamp except that it also provides the values contained in params.

See also
FooDataWriter_write_w_params
FooDataWriter_dispose_w_params

◆ FooDataWriter_write()

DDS_ReturnCode_t FooDataWriter_write ( FooDataWriter self,
const Foo instance_data,
const DDS_InstanceHandle_t handle 
)

Modifies the value of a data instance.

When this operation is used, RTI Connext 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 and DESTINATION_ORDER QoS policy 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 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 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.

This operation may also block when using DDS_BEST_EFFORT_RELIABILITY_QOS and DDS_ASYNCHRONOUS_PUBLISH_MODE_QOS. In this case, the DDS_DataWriter will queue DDS samples until they are sent by the asynchronous publishing thread. The number of DDS samples that can be stored is determined by the DDS_HistoryQosPolicy. If the asynchronous thread does not send DDS samples fast enough (such as when using a slow DDS_FlowController, the queue may fill up. In that case, subsequent write calls will block.

If DDS_ReliabilityQosPolicy::max_blocking_time elapses before the DDS_DataWriter can store the modification without exceeding the limits, the operation will fail and return DDS_RETCODE_TIMEOUT for KEEP_ALL configurations.

Here is how the write operation behaves when DDS_KEEP_LAST_HISTORY_QOS and DDS_RELIABLE_RELIABILITY_QOS are used:

Here is how the write operation behaves when DDS_KEEP_ALL_HISTORY_QOS and DDS_RELIABLE_RELIABILITY_QOS are used:

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.

This operation will fail with DDS_RETCODE_PRECONDITION_NOT_MET if the timestamp is less than the timestamp used in the last writer operation (register, unregister, dispose, or write, with either the automatically supplied timestamp or the application-provided timestamp).

If an instance obtained from FooDataWriter_get_loan is modified with this operation, then all instances modified thereafter should be from FooDataWriter_get_loan.

See DDS_ReliabilityQosPolicyAcknowledgmentModeKind for more information on the following notes:

(1) A sample in the writer history is considered "protocol ACKed" when the sample has been individually ACKed at the RTPS protocol level by each one of the DataReaders that matched the DataWriter at the moment the sample was added to the writer queue.

  • Late joiners do not change the protocol ACK state of a sample. If a sample is marked as protocol ACKed because it has been acknowledged by all the matching DataReaders and a DataReader joins later on, the historical sample is still considered protocol ACKed even if it has not been received by the late joiner.
  • If a sample 'S1' is protocol ACKed and a TopicQuery is received, triggering the publication of 'S1', the sample is still considered protocol ACKed. If a sample 'S1' is not ACKed and a TopicQuery is received triggering the publication of 'S1', the DataWriter will require that both the matching DataReaders on the live RTPS channel and the DataReader on the TopicQuery channel individually protocol ACK the sample in order to consider the sample protocol ACKed.

(2) A sample in the writer history is considered "fully ACKed" when all of the following conditions are met:

(3) It is possible within a single call to the write operation for a DataWriter to block both when the send window is full and then again when DDS_ResourceLimitsQosPolicy::max_samples or DDS_ResourceLimitsQosPolicy::max_samples_per_instance is exceeded. This can happen because blocking on the send window only considers protocol-ACKed samples, while blocking based on resource limits considers fully-ACKed samples. In any case, the total max blocking time of a single call to the write operation will not exceed DDS_ReliabilityQosPolicy::max_blocking_time.

Parameters
self<<in>> Cannot be NULL.
instance_data<<in>> The data to write.

This function will fail with DDS_RETCODE_BAD_PARAMETER if instance_data is NULL.

Parameters
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 function may fail with DDS_RETCODE_BAD_PARAMETER. This function will fail with DDS_RETCODE_BAD_PARAMETER if handle is NULL.
Returns
One of the Standard Return Codes, DDS_RETCODE_TIMEOUT, DDS_RETCODE_PRECONDITION_NOT_MET, DDS_RETCODE_OUT_OF_RESOURCES, or DDS_RETCODE_NOT_ENABLED.
MT Safety:
It is UNSAFE to modify instance_data before the operation has finished. The operation is otherwise SAFE.
See also
DDS_DataReader
FooDataWriter_write_w_timestamp
DESTINATION_ORDER

◆ FooDataWriter_write_w_timestamp()

DDS_ReturnCode_t FooDataWriter_write_w_timestamp ( FooDataWriter self,
const Foo 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 and DESTINATION_ORDER QoS policy for 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
self<<in>> Cannot be NULL.
instance_data<<in>> The data to write. This function 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 function may fail with DDS_RETCODE_BAD_PARAMETER. This function will fail with DDS_RETCODE_BAD_PARAMETER if handle is NULL.
source_timestamp<<in>> When using DDS_BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS the timestamp value must be greater than or equal to the timestamp value used in the last writer operation (register, unregister, dispose, or write, with either the automatically supplied timestamp or the application-provided timestamp) However, if it is less than the timestamp of the previous operation but the difference is less than the DDS_DestinationOrderQosPolicy::source_timestamp_tolerance, the timestamp of the previous operation will be used as the source timestamp of this sample. Otherwise, if the difference is greater than DDS_DestinationOrderQosPolicy::source_timestamp_tolerance, the function will return DDS_RETCODE_BAD_PARAMETER.

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
DESTINATION_ORDER

◆ FooDataWriter_write_w_params()

DDS_ReturnCode_t FooDataWriter_write_w_params ( FooDataWriter self,
const Foo instance_data,
struct DDS_WriteParams_t params 
)

Performs the same function as FooDataWriter_write and FooDataWriter_write_w_timestamp except that it also provides the values contained in params.

Allows provision of the sample identity, related sample identity, source timestamp, instance handle, and publication priority contained in params.

This operation may block and time out (DDS_RETCODE_TIMEOUT) under the same circumstances 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_w_params may help free up some resources.

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

Parameters
self<<in>> Cannot be NULL.
instance_data<<in>> The data to write. This function will fail with DDS_RETCODE_BAD_PARAMETER if instance_data is NULL.
params<<inout>> The write parameters. Note that this is an inout parameter if you activate DDS_WriteParams_t::replace_auto; otherwise it won't be modified. This function will fail with DDS_RETCODE_BAD_PARAMETER if params is 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

◆ FooDataWriter_dispose()

DDS_ReturnCode_t FooDataWriter_dispose ( FooDataWriter self,
const Foo instance_data,
const DDS_InstanceHandle_t instance_handle 
)

Requests the middleware to delete the instance.

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

When an instance is disposed, the DDS_DataWriter communicates this state change to DDS_DataReader objects by propagating a dispose sample. When the instance changes to a disposed state, you can see the state change on the DataReader by looking at DDS_SampleInfo::instance_state. Disposed instances have the value DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE.

The resources allocated to dispose instances on the DataWriter are not removed by default. The removal of the resources allocated to a dispose instance on the DataWriter queue can be controlled by using the QoS DDS_WriterDataLifecycleQosPolicy::autopurge_disposed_instances_delay.

Likewise, on the DataReader, the removal of the resources associated with an instance in the dispose state can be controlled by using the QoS DDS_ReaderDataLifecycleQosPolicy::autopurge_disposed_instances_delay.

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 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 instance_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 will not detect the error when the instance_handle is any value other than DDS_HANDLE_NIL, and the instance_handle 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). In this case, the instance that will be disposed is the instance corresponding to the instance_handle, not to the instance_data.

This operation may block and time out (DDS_RETCODE_TIMEOUT) under the same circumstances 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.

Parameters
self<<in>> Cannot be NULL.
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 function will fail with DDS_RETCODE_BAD_PARAMETER.
instance_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 it is deduced from instance_data. If Foo has no key, instance_handle is not used. If instance_handle is used, it must represent an instance of type Foo that has been written or registered with this writer. Otherwise, this function fail with DDS_RETCODE_BAD_PARAMETER. This function will fail with DDS_RETCODE_BAD_PARAMETER if instance_handle is NULL. If Foo has a key, instance_handle cannot be DDS_HANDLE_NIL if instance_data is NULL. Otherwise, this function 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
Relationship between registration, liveliness and ownership

◆ FooDataWriter_dispose_w_timestamp()

DDS_ReturnCode_t FooDataWriter_dispose_w_timestamp ( FooDataWriter self,
const Foo instance_data,
const DDS_InstanceHandle_t instance_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
self<<in>> Cannot be NULL.
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 function will fail with DDS_RETCODE_BAD_PARAMETER.
instance_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 function may fail with DDS_RETCODE_BAD_PARAMETER. This function 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_dispose

◆ FooDataWriter_dispose_w_params()

DDS_ReturnCode_t FooDataWriter_dispose_w_params ( FooDataWriter self,
const Foo instance_data,
struct DDS_WriteParams_t params 
)

Performs the same function as FooDataWriter_dispose and FooDataWriter_dispose_w_timestamp except that it also provides the values contained in params.

See also
FooDataWriter_write_w_params

◆ FooDataWriter_get_key_value()

DDS_ReturnCode_t FooDataWriter_get_key_value ( FooDataWriter self,
Foo key_holder,
const DDS_InstanceHandle_t handle 
)

Retrieve the instance key that corresponds to an instance handle.

Useful for keyed data types.

The operation will only fill the fields that form the key inside the key_holder instance. If the type has no keys, this function has no effect and exits with no error.

For keyed data types, this operation may fail with DDS_RETCODE_BAD_PARAMETER if the handle does not correspond to an existing data-object known to the DDS_DataWriter.

Parameters
self<<in>> Cannot be NULL.
key_holder<<inout>> a user data type specific key holder, whose key fields are filled by this operation. If Foo has no key, this function has no effect.

This function will fail with DDS_RETCODE_BAD_PARAMETER if key_holder is NULL.

Parameters
handle<<in>> the instance whose key is to be retrieved. If Foo has a key, handle must represent a registered instance of type Foo. Otherwise, this function will fail with DDS_RETCODE_BAD_PARAMETER. If Foo has a key and handle is DDS_HANDLE_NIL, this function will fail with DDS_RETCODE_BAD_PARAMETER. This function will fail with DDS_RETCODE_BAD_PARAMETER if handle is NULL.
Returns
One of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.
See also
FooDataReader_get_key_value

◆ FooDataWriter_lookup_instance()

DDS_InstanceHandle_t FooDataWriter_lookup_instance ( FooDataWriter self,
const Foo key_holder 
)

Retrieve the instance handle that corresponds to an instance key_holder.

Useful for keyed data types.

This operation takes as a parameter an instance and returns a handle that can be used in subsequent operations that accept an instance handle as an argument. The instance parameter is only used for the purpose of examining the fields that define the key. This operation does not register the instance in question. If the instance has not been previously registered, or if for any other reason RTI Connext is unable to provide an instance handle, RTI Connext will return the special value HANDLE_NIL.

Parameters
self<<in>> Cannot be NULL.
key_holder<<in>> a user data type specific key holder.
Returns
the instance handle associated with this instance. If Foo has no key, this function has no effect and returns DDS_HANDLE_NIL

◆ FooDataWriter_create_data()

void * FooDataWriter_create_data ( FooDataWriter self)

Creates a data sample and initializes it.

The behavior of this API is identical to FooTypeSupport_create_data.

Parameters
self<<in>> Cannot be NULL.
Returns
Newly created data type, or NULL on failure.
See also
FooDataWriter_delete_data

◆ FooDataWriter_create_data_w_params()

void * FooDataWriter_create_data_w_params ( FooDataWriter self,
const struct DDS_TypeAllocationParams_t alloc_params 
)

Creates a data sample and initializes it.

The behavior of this API is identical to FooTypeSupport_create_data_w_params.

Parameters
self<<in>> Cannot be NULL.
alloc_params<<in>> Whether or not to recursively allocate pointers and/or optional members
Returns
Newly created data type, or NULL on failure.
See also
FooDataWriter_delete_data_w_params

◆ FooDataWriter_delete_data()

DDS_Boolean FooDataWriter_delete_data ( FooDataWriter self,
Foo sample 
)

Destroys a user data type instance.

The behavior of this API is identical to FooTypeSupport_delete_data.

Parameters
self<<in>> Cannot be NULL.
sample<<in>> Cannot be NULL.
Returns
DDS_BOOLEAN_TRUE on success.
See also
FooDataWriter_create_data

◆ FooDataWriter_delete_data_w_params()

void * FooDataWriter_delete_data_w_params ( FooDataWriter self,
Foo sample,
const struct DDS_TypeDeallocationParams_t dealloc_params 
)

Destroys a user data type instance.

The behavior of this API is identical to FooTypeSupport_delete_data_w_params.

Parameters
self<<in>> Cannot be NULL.
sample<<in>> Cannot be NULL.
dealloc_params<<in>> Whether or not to destroy pointers and/or optional members.
Returns
DDS_BOOLEAN_TRUE on success.
See also
FooDataWriter_create_data_w_params

◆ FooDataWriter_get_loan()

DDS_ReturnCode_t FooDataWriter_get_loan ( FooDataWriter self,
Foo **  sample 
)

Gets a sample managed by the DataWriter.

This operation is supported while using Zero Copy transfer over shared memory" or \ref RTIFlatDataModule "FlatData language binding".

The loaned sample is obtained from a DataWriter-managed sample pool and is uninitialized by default. An initialized sample can be obtained by setting DDS_DataWriterResourceLimitsQosPolicy::initialize_writer_loaned_sample to DDS_BOOLEAN_TRUE. The DDS_DataWriterResourceLimitsQosPolicy::writer_loaned_sample_allocation settings can be used to configure the DataWriter-managed sample pool.

FooDataWriter_get_loan fails with DDS_RETCODE_OUT_OF_RESOURCES if DDS_AllocationSettings_t::max_count samples have been loaned, and none of those samples has been written with FooDataWriter_write or discarded via FooDataWriter_discard_loan.

Samples returned from FooDataWriter_get_loan have an associated state. Due to the optimized nature of the write operation while using Zero Copy transfer over shared memory or FlatData language binding, this sample state is used to control when a sample is available for reuse after the write operation. The possible sample states are free, allocated, removed or serialized. A sample that has never been allocated is "free". FooDataWriter_get_loan takes a "free" or "removed" sample and makes it "allocated". When a sample is written, its state transitions from "allocated" to "serialized", and the DataWriter takes responsibility for returning the sample back to its sample pool. The sample remains in the "serialized" state until it is removed from the DataWriter queue. For a reliable DataWriter, the sample is removed from the DataWriter's queue when the sample is acknowledged by all DataReaders. For a best-effort DataWriter, the sample is removed from the queue immediately after the write operation. After the sample is removed from the DataWriter queue, the sample is put back into the sample pool, and its state transitions from "serialized" to "removed". At this time, a new call to FooDataWriter_get_loan may return the same sample.

A loaned sample should not be reused to write a new value after the first write operation. Instead, a new sample from FooDataWriter_get_loan should be used to write the new value. A loaned sample that has not been written can be returned to the DataWriter's sample pool by using FooDataWriter_discard_loan. If the write operation fails, then the sample can be used again with a write or discard_loan operation. Disposing or unregistering an instance with loaned samples follows the same pattern. A loaned sample used successfully with a dispose or unregister operation cannot be used again. But if the dispose or unregister operation fails, the sample is available for reuse.

A DataWriter cannot write managed samples (created with get_loan) and unmanaged samples (created in any other way) at the same time. The first call to get_loan automatically prepares this DataWriter to work with managed samples. Calls to get_loan will fail with DDS_RETCODE_PRECONDITION_NOT_MET if an unmanaged sample was written with this DataWriter earlier. Similarly, FooDataWriter_write will fail to write an unmanaged sample if get_loan was called.

Parameters
self<<in>> Cannot be NULL.
sample<<inout>> address of a user data type pointer. The loaned sample is returned via this sample.
Returns
One of the Standard Return Codes, DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_PRECONDITION_NOT_MET.
See also
FooDataWriter_discard_loan

◆ FooDataWriter_discard_loan()

DDS_ReturnCode_t FooDataWriter_discard_loan ( FooDataWriter self,
Foo sample 
)

Returns a loaned sample back to the DataWriter.

This operation is supported while using Zero Copy transfer over shared memory" or the FlatData language binding.

A loaned sample that hasn't been written can be returned to the DataWriter with this operation.

Parameters
self<<in>> Cannot be NULL.
sample<<in>> loaned sample to be discarded.
Returns
One of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.
See also
FooDataWriter_get_loan

◆ DDS_OfferedDeadlineMissedStatus_initialize()

DDS_ReturnCode_t DDS_OfferedDeadlineMissedStatus_initialize ( struct DDS_OfferedDeadlineMissedStatus self)

Initializer for new status instances.

New DDS_OfferedDeadlineMissedStatus instance on heap should be initialized with this function before they are passed to any function. This step ensures that those contained fields that use dynamic memory are properly initialized. This function does not allocate memory.

DDS_OfferedDeadlineMissedStatus_finalize should be called to free the contained fields that use dynamic memory:

free(myStatus);
DDS_ReturnCode_t DDS_OfferedDeadlineMissedStatus_initialize(struct DDS_OfferedDeadlineMissedStatus *self)
Initializer for new status instances.
Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_DataWriter_get_offered_deadline_missed_status
DDS_OfferedDeadlineMissedStatus_finalize

◆ DDS_OfferedDeadlineMissedStatus_copy()

DDS_ReturnCode_t DDS_OfferedDeadlineMissedStatus_copy ( struct DDS_OfferedDeadlineMissedStatus self,
const struct DDS_OfferedDeadlineMissedStatus source 
)

Copy the contents of the given status into this status.

Status instances can use dynamic memory because of the sequences contained in some status. A shallow copy by assignment is therefore unsafe. This function performs a deep-copy, allocating memory if necessary.

Parameters
self<<in>> Cannot be NULL.
source<<in>>. Status to be copied from.
Returns
One of the Standard Return Codes
See also
DDS_OfferedDeadlineMissedStatus_INITIALIZER
DDS_OfferedDeadlineMissedStatus_initialize
DDS_OfferedDeadlineMissedStatus_finalize

◆ DDS_OfferedDeadlineMissedStatus_finalize()

DDS_ReturnCode_t DDS_OfferedDeadlineMissedStatus_finalize ( struct DDS_OfferedDeadlineMissedStatus self)

Free any dynamic memory allocated by status instances.

some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status 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).

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

Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_OfferedDeadlineMissedStatus_INITIALIZER
DDS_OfferedDeadlineMissedStatus_initialize

◆ DDS_LivelinessLostStatus_initialize()

DDS_ReturnCode_t DDS_LivelinessLostStatus_initialize ( struct DDS_LivelinessLostStatus self)

Initializer for new status instances.

New DDS_LivelinessLostStatus instance on heap should be initialized with this function before they are passed to any function. This step ensures that those contained fields that use dynamic memory are properly initialized. This function does not allocate memory.

DDS_LivelinessLostStatus_finalize should be called to free the contained fields that use dynamic memory:

DDS_LivelinessLostStatus *myStatus = malloc(sizeof(struct DDS_LivelinessLostStatus));
free(myStatus);
DDS_ReturnCode_t DDS_LivelinessLostStatus_initialize(struct DDS_LivelinessLostStatus *self)
Initializer for new status instances.
Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_DataWriter_get_liveliness_lost_status
DDS_LivelinessLostStatus_finalize

◆ DDS_LivelinessLostStatus_copy()

DDS_ReturnCode_t DDS_LivelinessLostStatus_copy ( struct DDS_LivelinessLostStatus self,
const struct DDS_LivelinessLostStatus source 
)

Copy the contents of the given status into this status.

Status instances can use dynamic memory because of the sequences contained in some status. A shallow copy by assignment is therefore unsafe. This function performs a deep-copy, allocating memory if necessary.

Parameters
self<<in>> Cannot be NULL.
source<<in>>. Status to be copied from.
Returns
One of the Standard Return Codes
See also
DDS_LivelinessLostStatus_INITIALIZER
DDS_LivelinessLostStatus_initialize
DDS_LivelinessLostStatus_finalize

◆ DDS_LivelinessLostStatus_finalize()

DDS_ReturnCode_t DDS_LivelinessLostStatus_finalize ( struct DDS_LivelinessLostStatus self)

Free any dynamic memory allocated by status instances.

some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status 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).

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

Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_LivelinessLostStatus_INITIALIZER
DDS_LivelinessLostStatus_initialize

◆ DDS_OfferedIncompatibleQosStatus_initialize()

DDS_ReturnCode_t DDS_OfferedIncompatibleQosStatus_initialize ( struct DDS_OfferedIncompatibleQosStatus self)

Initializer for new status instances.

New DDS_OfferedIncompatibleQosStatus instance on heap should be initialized with this function before they are passed to any function. This step ensures that those contained fields that use dynamic memory are properly initialized. This function does not allocate memory.

DDS_OfferedIncompatibleQosStatus_finalize should be called to free the contained fields that use dynamic memory:

free(myStatus);
DDS_ReturnCode_t DDS_OfferedIncompatibleQosStatus_initialize(struct DDS_OfferedIncompatibleQosStatus *self)
Initializer for new status instances.
Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_DataWriter_get_offered_incompatible_qos_status
DDS_OfferedIncompatibleQosStatus_finalize

◆ DDS_OfferedIncompatibleQosStatus_copy()

DDS_ReturnCode_t DDS_OfferedIncompatibleQosStatus_copy ( struct DDS_OfferedIncompatibleQosStatus self,
const struct DDS_OfferedIncompatibleQosStatus source 
)

Copy the contents of the given status into this status.

Status instances can use dynamic memory because of the sequences contained in some status. A shallow copy by assignment is therefore unsafe. This function performs a deep-copy, allocating memory if necessary.

Parameters
self<<in>> Cannot be NULL.
source<<in>>. Status to be copied from.
Returns
One of the Standard Return Codes
See also
DDS_OfferedIncompatibleQosStatus_INITIALIZER
DDS_OfferedIncompatibleQosStatus_initialize
DDS_OfferedIncompatibleQosStatus_finalize

◆ DDS_OfferedIncompatibleQosStatus_finalize()

DDS_ReturnCode_t DDS_OfferedIncompatibleQosStatus_finalize ( struct DDS_OfferedIncompatibleQosStatus self)

Free any dynamic memory allocated by status instances.

some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status 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).

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

Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_OfferedIncompatibleQosStatus_INITIALIZER
DDS_OfferedIncompatibleQosStatus_initialize

◆ DDS_PublicationMatchedStatus_initialize()

DDS_ReturnCode_t DDS_PublicationMatchedStatus_initialize ( struct DDS_PublicationMatchedStatus self)

Initializer for new status instances.

New DDS_PublicationMatchedStatus instance on heap should be initialized with this function before they are passed to any function. This step ensures that those contained fields that use dynamic memory are properly initialized. This function does not allocate memory.

DDS_PublicationMatchedStatus_finalize should be called to free the contained fields that use dynamic memory:

DDS_PublicationMatchedStatus *myStatus = malloc(sizeof(struct DDS_PublicationMatchedStatus));
free(myStatus);
DDS_ReturnCode_t DDS_PublicationMatchedStatus_initialize(struct DDS_PublicationMatchedStatus *self)
Initializer for new status instances.
Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_DataWriter_get_publication_matched_status
DDS_PublicationMatchedStatus_finalize

◆ DDS_PublicationMatchedStatus_copy()

DDS_ReturnCode_t DDS_PublicationMatchedStatus_copy ( struct DDS_PublicationMatchedStatus self,
const struct DDS_PublicationMatchedStatus source 
)

Copy the contents of the given status into this status.

Status instances can use dynamic memory because of the sequences contained in some status. A shallow copy by assignment is therefore unsafe. This function performs a deep-copy, allocating memory if necessary.

Parameters
self<<in>> Cannot be NULL.
source<<in>>. Status to be copied from.
Returns
One of the Standard Return Codes
See also
DDS_PublicationMatchedStatus_INITIALIZER
DDS_PublicationMatchedStatus_initialize
DDS_PublicationMatchedStatus_finalize

◆ DDS_PublicationMatchedStatus_finalize()

DDS_ReturnCode_t DDS_PublicationMatchedStatus_finalize ( struct DDS_PublicationMatchedStatus self)

Free any dynamic memory allocated by status instances.

some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status 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).

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

Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_PublicationMatchedStatus_INITIALIZER
DDS_PublicationMatchedStatus_initialize

◆ DDS_ServiceRequestAcceptedStatus_initialize()

DDS_ReturnCode_t DDS_ServiceRequestAcceptedStatus_initialize ( struct DDS_ServiceRequestAcceptedStatus self)

Initializer for new status instances.

New DDS_ServiceRequestAcceptedStatus instance on heap should be initialized with this function before they are passed to any function. This step ensures that those contained fields that use dynamic memory are properly initialized. This function does not allocate memory.

DDS_ServiceRequestAcceptedStatus_finalize should be called to free the contained fields that use dynamic memory:

free(myStatus);
DDS_ReturnCode_t DDS_ServiceRequestAcceptedStatus_initialize(struct DDS_ServiceRequestAcceptedStatus *self)
Initializer for new status instances.
Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_DataWriter_get_service_request_accepted_status
DDS_ServiceRequestAcceptedStatus_finalize

◆ DDS_ServiceRequestAcceptedStatus_copy()

DDS_ReturnCode_t DDS_ServiceRequestAcceptedStatus_copy ( struct DDS_ServiceRequestAcceptedStatus self,
const struct DDS_ServiceRequestAcceptedStatus source 
)

Copy the contents of the given status into this status.

Status instances can use dynamic memory because of the sequences contained in some status. A shallow copy by assignment is therefore unsafe. This function performs a deep-copy, allocating memory if necessary.

Parameters
self<<in>> Cannot be NULL.
source<<in>>. Status to be copied from.
Returns
One of the Standard Return Codes
See also
DDS_ServiceRequestAcceptedStatus_INITIALIZER
DDS_ServiceRequestAcceptedStatus_initialize
DDS_ServiceRequestAcceptedStatus_finalize

◆ DDS_ServiceRequestAcceptedStatus_finalize()

DDS_ReturnCode_t DDS_ServiceRequestAcceptedStatus_finalize ( struct DDS_ServiceRequestAcceptedStatus self)

Free any dynamic memory allocated by status instances.

some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status 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).

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

Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_ServiceRequestAcceptedStatus_INITIALIZER
DDS_ServiceRequestAcceptedStatus_initialize

◆ DDS_ReliableWriterCacheChangedStatus_initialize()

DDS_ReturnCode_t DDS_ReliableWriterCacheChangedStatus_initialize ( struct DDS_ReliableWriterCacheChangedStatus self)

Initializer for new status instances.

New DDS_ReliableWriterCacheChangedStatus instance on heap should be initialized with this function before they are passed to any function. This step ensures that those contained fields that use dynamic memory are properly initialized. This function does not allocate memory.

DDS_ReliableWriterCacheChangedStatus_finalize should be called to free the contained fields that use dynamic memory:

free(myStatus);
DDS_ReturnCode_t DDS_ReliableWriterCacheChangedStatus_initialize(struct DDS_ReliableWriterCacheChangedStatus *self)
Initializer for new status instances.
Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_DataWriter_get_reliable_writer_cache_changed_status
DDS_ReliableWriterCacheChangedStatus_finalize

◆ DDS_ReliableWriterCacheChangedStatus_copy()

DDS_ReturnCode_t DDS_ReliableWriterCacheChangedStatus_copy ( struct DDS_ReliableWriterCacheChangedStatus self,
const struct DDS_ReliableWriterCacheChangedStatus source 
)

Copy the contents of the given status into this status.

Status instances can use dynamic memory because of the sequences contained in some status. A shallow copy by assignment is therefore unsafe. This function performs a deep-copy, allocating memory if necessary.

Parameters
self<<in>> Cannot be NULL.
source<<in>>. Status to be copied from.
Returns
One of the Standard Return Codes
See also
DDS_ReliableWriterCacheChangedStatus_INITIALIZER
DDS_ReliableWriterCacheChangedStatus_initialize
DDS_ReliableWriterCacheChangedStatus_finalize

◆ DDS_ReliableWriterCacheChangedStatus_finalize()

DDS_ReturnCode_t DDS_ReliableWriterCacheChangedStatus_finalize ( struct DDS_ReliableWriterCacheChangedStatus self)

Free any dynamic memory allocated by status instances.

some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status 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).

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

Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_ReliableWriterCacheChangedStatus_INITIALIZER
DDS_ReliableWriterCacheChangedStatus_initialize

◆ DDS_ReliableReaderActivityChangedStatus_initialize()

DDS_ReturnCode_t DDS_ReliableReaderActivityChangedStatus_initialize ( struct DDS_ReliableReaderActivityChangedStatus self)

Initializer for new status instances.

New DDS_ReliableReaderActivityChangedStatus instance on heap should be initialized with this function before they are passed to any function. This step ensures that those contained fields that use dynamic memory are properly initialized. This function does not allocate memory.

DDS_ReliableReaderActivityChangedStatus_finalize should be called to free the contained fields that use dynamic memory:

free(myStatus);
DDS_ReturnCode_t DDS_ReliableReaderActivityChangedStatus_initialize(struct DDS_ReliableReaderActivityChangedStatus *self)
Initializer for new status instances.
Returns
One of the Standard Return Codes
See also
DDS_DataWriter_get_reliable_reader_activity_changed_status
DDS_ReliableReaderActivityChangedStatus_finalize

◆ DDS_ReliableReaderActivityChangedStatus_copy()

DDS_ReturnCode_t DDS_ReliableReaderActivityChangedStatus_copy ( struct DDS_ReliableReaderActivityChangedStatus self,
const struct DDS_ReliableReaderActivityChangedStatus source 
)

Copy the contents of the given status into this status.

Status instances can use dynamic memory because of the sequences contained in some status. A shallow copy by assignment is therefore unsafe. This function performs a deep-copy, allocating memory if necessary.

Parameters
self<<in>> Cannot be NULL.
source<<in>>. Status to be copied from.
Returns
One of the Standard Return Codes
See also
DDS_ReliableReaderActivityChangedStatus_INITIALIZER
DDS_ReliableReaderActivityChangedStatus_initialize
DDS_ReliableReaderActivityChangedStatus_finalize

◆ DDS_ReliableReaderActivityChangedStatus_finalize()

DDS_ReturnCode_t DDS_ReliableReaderActivityChangedStatus_finalize ( struct DDS_ReliableReaderActivityChangedStatus self)

Free any dynamic memory allocated by status instances.

some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status 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).

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

Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_ReliableReaderActivityChangedStatus_INITIALIZER
DDS_ReliableReaderActivityChangedStatus_initialize

◆ DDS_DataWriterCacheStatus_initialize()

DDS_ReturnCode_t DDS_DataWriterCacheStatus_initialize ( struct DDS_DataWriterCacheStatus self)

Initializer for new status instances.

New DDS_DataWriterCacheStatus instance on heap should be initialized with this function before they are passed to any function. This step ensures that those contained fields that use dynamic memory are properly initialized. This function does not allocate memory.

DDS_DataWriterCacheStatus_finalize should be called to free the contained fields that use dynamic memory:

DDS_DataWriterCacheStatus *myStatus = malloc(sizeof(struct DDS_DataWriterCacheStatus));
free(myStatus);
DDS_ReturnCode_t DDS_DataWriterCacheStatus_initialize(struct DDS_DataWriterCacheStatus *self)
Initializer for new status instances.
Returns
One of the Standard Return Codes
See also
DDS_DataWriter_get_datawriter_cache_status
DDS_DataWriterCacheStatus_finalize

◆ DDS_DataWriterCacheStatus_copy()

DDS_ReturnCode_t DDS_DataWriterCacheStatus_copy ( struct DDS_DataWriterCacheStatus self,
const struct DDS_DataWriterCacheStatus source 
)

Copy the contents of the given status into this status.

Status instances can use dynamic memory because of the sequences contained in some status. A shallow copy by assignment is therefore unsafe. This function performs a deep-copy, allocating memory if necessary.

Parameters
self<<in>> Cannot be NULL.
source<<in>>. Status to be copied from.
Returns
One of the Standard Return Codes
See also
DDS_DataWriterCacheStatus_INITIALIZER
DDS_DataWriterCacheStatus_initialize
DDS_DataWriterCacheStatus_finalize

◆ DDS_DataWriterCacheStatus_finalize()

DDS_ReturnCode_t DDS_DataWriterCacheStatus_finalize ( struct DDS_DataWriterCacheStatus self)

Free any dynamic memory allocated by status instances.

some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status 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).

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

Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_DataWriterCacheStatus_INITIALIZER
DDS_DataWriterCacheStatus_initialize

◆ DDS_DataWriterProtocolStatus_initialize()

DDS_ReturnCode_t DDS_DataWriterProtocolStatus_initialize ( struct DDS_DataWriterProtocolStatus self)

Initializer for new status instances.

New DDS_DataWriterProtocolStatus instance on heap should be initialized with this function before they are passed to any function. This step ensures that those contained fields that use dynamic memory are properly initialized. This function does not allocate memory.

DDS_DataWriterProtocolStatus_finalize should be called to free the contained fields that use dynamic memory:

DDS_DataWriterProtocolStatus *myStatus = malloc(sizeof(struct DDS_DataWriterProtocolStatus));
free(myStatus);
DDS_ReturnCode_t DDS_DataWriterProtocolStatus_initialize(struct DDS_DataWriterProtocolStatus *self)
Initializer for new status instances.
Returns
One of the Standard Return Codes
See also
DDS_DataWriter_get_datawriter_protocol_status
DDS_DataWriterProtocolStatus_finalize

◆ DDS_DataWriterProtocolStatus_copy()

DDS_ReturnCode_t DDS_DataWriterProtocolStatus_copy ( struct DDS_DataWriterProtocolStatus self,
const struct DDS_DataWriterProtocolStatus source 
)

Copy the contents of the given status into this status.

Status instances can use dynamic memory because of the sequences contained in some status. A shallow copy by assignment is therefore unsafe. This function performs a deep-copy, allocating memory if necessary.

Parameters
self<<in>> Cannot be NULL.
source<<in>>. Status to be copied from.
Returns
One of the Standard Return Codes
See also
DDS_DataWriterProtocolStatus_INITIALIZER
DDS_DataWriterProtocolStatus_initialize
DDS_DataWriterProtocolStatus_finalize

◆ DDS_DataWriterProtocolStatus_finalize()

DDS_ReturnCode_t DDS_DataWriterProtocolStatus_finalize ( struct DDS_DataWriterProtocolStatus self)

Free any dynamic memory allocated by status instances.

some status may use dynamic memory (regardless of whether the status itself is in dynamic memory). This function frees that memory but otherwise leaves this status 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).

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

Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_DataWriterProtocolStatus_INITIALIZER
DDS_DataWriterProtocolStatus_initialize

◆ DDS_DataWriterQos_equals()

DDS_Boolean DDS_DataWriterQos_equals ( const struct DDS_DataWriterQos self,
const struct DDS_DataWriterQos other 
)

Compares two DDS_DataWriterQos for equality.

Parameters
self<<in>> This DataWriterQos.
other<<in>> The other DataWriterQos to be compared with this DataWriterQos.
Returns
DDS_BOOLEAN_TRUE if the two Qos objects are equal or DDS_BOOLEAN_FALSE otherwise.

◆ DDS_DataWriterQos_print()

DDS_ReturnCode_t DDS_DataWriterQos_print ( const struct DDS_DataWriterQos self)

Prints this DDS_DataWriterQos to stdout.

Only the differences between this DDS_DataWriterQos and the documented default are printed. If you wish to print everything regardless, see DDS_DataWriterQos_to_string_w_params. The output is formatted according to the default values for DDS_QosPrintFormat.

Parameters
self<<in>> Cannot be NULL.
Returns
DDS_RETCODE_OK if no error was encountered.

◆ DDS_DataWriterQos_to_string()

DDS_ReturnCode_t DDS_DataWriterQos_to_string ( const struct DDS_DataWriterQos self,
char *  string,
DDS_UnsignedLong string_size 
)

Obtains a string representation of this DDS_DataWriterQos.

Only the differences between this DDS_DataWriterQos and the documented default are printed to the string. If you wish to print everything regardless, see DDS_DataWriterQos_to_string_w_params. The output is formatted according to the default values for DDS_QosPrintFormat.

If the supplied buffer is NULL, the required length of the string is returned via the string_size parameter.

If the supplied buffer is not NULL, the string representation of the DDS_DataWriterQos is written to the buffer.

Parameters
self<<in>> Cannot be NULL.
string<<out>> The char buffer that will be used to store the string representation of this DDS_DataWriterQos. If NULL, this function will return the required length of this buffer through the string_size parameter.
string_size<<inout>> Cannot be NULL. The size of the supplied buffer. If the supplied buffer is NULL, or if the supplied buffer is not large enough, this value will be updated with the required length of the buffer.
Returns
DDS_RETCODE_OK if no error was encountered.
See also
DDS_DataWriterQos_to_string_w_params

◆ DDS_DataWriterQos_to_string_w_params()

DDS_ReturnCode_t DDS_DataWriterQos_to_string_w_params ( const struct DDS_DataWriterQos self,
char *  string,
DDS_UnsignedLong string_size,
const struct DDS_DataWriterQos base,
const struct DDS_QosPrintFormat format 
)

Obtains a string representation of this DDS_DataWriterQos.

Only the differences between this DDS_DataWriterQos and the DDS_DataWriterQos supplied as the base are printed to the string.

It is possible to supply the sentinel value DDS_DATAWRITER_QOS_PRINT_ALL as the base to print everything within the QoS.

If the supplied buffer is NULL, the required length of the string is returned via the string_size parameter.

If the supplied buffer is not NULL, the string representation of the DDS_DataWriterQos is written to the buffer.

Parameters
self<<in>> Cannot be NULL.
string<<out>> The char buffer that will be used to store the string representation of this DDS_DataWriterQos. If NULL, this function will return the required length of this buffer through the string_size parameter.
string_size<<inout>> Cannot be NULL. The size of the supplied buffer. If the supplied buffer is NULL, or if the supplied buffer is not large enough, this value will be updated with the required length of the buffer.
base<<in>> The DDS_DataWriterQos to be used as the base QoS profile. Only the differences with respect to this base profile will be included in the output string.
format<<in>> The DDS_QosPrintFormat to be used to format the output string.
Returns
DDS_RETCODE_OK if no error was encountered.

◆ DDS_DataWriterQos_initialize()

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 function before they are passed to any function. This step ensures that those contained QoS policies that use dynamic memory are properly initialized. This function does not allocate memory.

Calling this function is not a substitute for calling DDS_DataWriter_get_qos or DDS_Publisher_get_default_datawriter_qos; one of those should be called subsequently to setting the QoS of any new or existing entity. DDS_DataWriterQos_finalize should be called to free the contained QoS policies that use dynamic memory:

DDS_DataWriterQos *myQos = malloc(sizeof(struct DDS_DataWriterQos));
DDS_DataWriter_set_qos(myDataWriter, myQos);
free(myQos);
DDS_ReturnCode_t DDS_DataWriterQos_initialize(struct DDS_DataWriterQos *self)
Initializer for new QoS instances.
Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_Publisher_get_default_datawriter_qos
DDS_DataWriterQos_finalize

◆ 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 function 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 function 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 function will not call free() on it; the user is responsible for explicitly freeing any heap-based QoS instance after calling this function.

Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_DataWriterQos_INITIALIZER
DDS_DataWriterQos_initialize

◆ DDS_DataWriterQos_copy()

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 function performs a deep-copy, allocating memory if necessary.

Parameters
self<<in>> Cannot be NULL.
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_DataWriter_as_entity()

DDS_Entity * DDS_DataWriter_as_entity ( DDS_DataWriter dataWriter)

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_DataWriter_assert_liveliness()

DDS_ReturnCode_t DDS_DataWriter_assert_liveliness ( DDS_DataWriter self)

This operation manually asserts the liveliness of this DDS_DataWriter.

This is used in combination with the LIVELINESS policy to indicate to RTI Connext that the DDS_DataWriter remains active.

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

Note: writing data via the FooDataWriter_write or FooDataWriter_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.

Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED
See also
DDS_LivelinessQosPolicy

◆ DDS_DataWriter_get_matched_subscription_locators()

DDS_ReturnCode_t DDS_DataWriter_get_matched_subscription_locators ( DDS_DataWriter self,
struct DDS_LocatorSeq locators 
)

<<extension>> Retrieve the list of locators for subscriptions currently "associated" with this DDS_DataWriter.

The locators returned in the locators list are the ones that are used by the DDS implementation to communicate with the corresponding matched DDS_DataReader entities.

Parameters
self<<in>> Cannot be NULL.
locators<<inout>>. Handles of all the matched subscription locators.

The sequence will be grown if the sequence has ownership and the system has the corresponding resources. Use a sequence without ownership to avoid dynamic memory allocation. If the sequence is too small to store all the matches and the system can not resize the sequence, this function will fail with DDS_RETCODE_OUT_OF_RESOURCES. Cannot be NULL. .

Returns
One of the Standard Return Codes, or DDS_RETCODE_OUT_OF_RESOURCES if the sequence is too small and the system can not resize it, or DDS_RETCODE_NOT_ENABLED

◆ DDS_DataWriter_get_matched_subscriptions()

DDS_ReturnCode_t DDS_DataWriter_get_matched_subscriptions ( DDS_DataWriter self,
struct DDS_InstanceHandleSeq subscription_handles 
)

Retrieve the list of subscriptions currently "associated" with this DDS_DataWriter.

A subscription is considered to be matching if all of the following criteria are true:

  • The subscription is within the same domain as this publication.
  • The subscription has a matching DDS_Topic.
  • The subscription has compatible QoS.
  • If the applications are using partitions, the subscription shares a common partition with this publication.
  • The DDS_DomainParticipant has not indicated that the subscription's DDS_DomainParticipant should be "ignored" by means of the DDS_DomainParticipant_ignore_publication API.
  • If the publication is using the DDS_MultiChannelQosPolicy and the subscription is using a DDS_ContentFilteredTopic, there is an intersection between at least one of the associated filters.
  • If the endpoints need to exchange key material to communicate (i.e., they are securing their communications), the writer has completed the key exchange with reader.

The handles returned in the subscription_handles list are the ones that RTI Connext uses to locally identify the corresponding matched DDS_DataReader entities. These handles match the ones that appear in the DDS_SampleInfo::instance_handle field of the DDS_SampleInfo when reading the DDS_SUBSCRIPTION_TOPIC_NAME builtin topic.

This API may return the subscription handles of subscriptions that are inactive. DDS_DataWriter_is_matched_subscription_active can be used to check this.

Parameters
self<<in>> Cannot be NULL.
subscription_handles<<inout>>. The handles of all the matched subscriptions.

The sequence will be grown if the sequence has ownership and the system has the corresponding resources. Use a sequence without ownership to avoid dynamic memory allocation. If the sequence is too small to store all of the matches and the system cannot resize the sequence, this function will fail with DDS_RETCODE_OUT_OF_RESOURCES.

The maximum number of matches possible is configured with DDS_DomainParticipantResourceLimitsQosPolicy. You can use a zero-maximum sequence without ownership to quickly check whether there are any matches without allocating any memory. Cannot be NULL. .

Returns
One of the Standard Return Codes, or DDS_RETCODE_OUT_OF_RESOURCES if the sequence is too small and the system cannot resize it, or DDS_RETCODE_NOT_ENABLED

◆ DDS_DataWriter_is_matched_subscription_active()

DDS_ReturnCode_t DDS_DataWriter_is_matched_subscription_active ( DDS_DataWriter self,
DDS_Boolean is_active,
const DDS_InstanceHandle_t subscription_handle 
)

Check if a subscription currently matched with a DataWriter is active.

This API is used for querying the endpoint liveliness of a matched subscription. A matched subscription will be marked as inactive when it becomes nonprogessing (e.g., not responding to a DataWriter's heartbeats, or letting its internal queue fill up without taking the available data). Note that if the participant associated with the matched subscription loses liveliness, the DDS_InstanceHandle_t will become invalid and this function will fail with DDS_RETCODE_BAD_PARAMETER.

Parameters
self<<in>> Cannot be NULL.
subscription_handle<<in>> The DDS_InstanceHandle_t of the matched subscription. See DDS_DataWriter_get_matched_subscriptions for a description of what is considered a matched subscription.
is_active<<out>> Indicates whether or not the matched subscription is active.
Returns
One of the Standard Return Codes

◆ DDS_DataWriter_get_matched_subscription_data()

DDS_ReturnCode_t DDS_DataWriter_get_matched_subscription_data ( DDS_DataWriter self,
struct DDS_SubscriptionBuiltinTopicData subscription_data,
const DDS_InstanceHandle_t subscription_handle 
)

This operation retrieves the information on a subscription that is currently "associated" with the DDS_DataWriter.

The subscription_handle must correspond to a subscription currently associated with the DDS_DataWriter. Otherwise, the operation will fail and fail with DDS_RETCODE_BAD_PARAMETER. Use DDS_DataWriter_get_matched_subscriptions to find the subscriptions that are currently matched with the DDS_DataWriter.

The above information is also available through DDS_DataReaderListener::on_data_available() (if a reader listener is installed on the DDS_SubscriptionBuiltinTopicDataDataReader).

When the subscription data is updated, for example when the content filter property changes, there is a small window of time in between when the DataWriter is made aware of these changes and when they actually take effect. Taking effect in this example means that the DataWriter will perform writer-side filtering using the new filter property values (filter expression and/or parameters).

When the DataWriter is made aware of the changes they will first be seen in the DDS_DataReaderListener::on_data_available() of the DDS_SubscriptionBuiltinTopicDataDataReader. When these changes are applied, they will be seen in the output of this API because this API blocks until the most recent changes known to the DataWriter have taken effect. This API will only block when called outside of a listener callback, in order to not block the internal threads from making progress.

If application behavior depends on being made aware of information about a subscription only after it has taken effect on the DataWriter, the recommended pattern for usage of this API is to wait for subscription data to be received either through polling this API or by installing a listener on the DDS_SubscriptionBuiltinTopicDataDataReader. When a new sample is received by the builtin DataReader, this API may be called in a separate thread and will return the expected matched subscription data once it has been applied to the DataWriter.

Because this API blocks, it is possible for this API to time out while waiting for the changes to be applied. A timeout may happen if the DataReader's subscription data is changing rapidly, preventing the DataWriter from returning valid information before newer data has been received, or if an application is performing a task in a listener callback, thereby preventing the middleware's threads from executing events in a timely manner.

Note: This operation does not retrieve the DDS_SubscriptionBuiltinTopicData::type_code. This information is available through DDS_DataReaderListener::on_data_available() (if a reader listener is installed on the DDS_SubscriptionBuiltinTopicDataDataReader).

Parameters
self<<in>> Cannot be NULL.
subscription_data<<inout>>. The information to be filled in on the associated subscription. Cannot be NULL.
subscription_handle<<in>>. Handle to a specific subscription associated with the DDS_DataReader. Must correspond to a subscription currently associated with the DDS_DataWriter. Cannot be NULL.
Returns
One of the Standard Return Codes, DDS_RETCODE_NOT_ENABLED, or DDS_RETCODE_TIMEOUT

◆ DDS_DataWriter_get_matched_subscription_participant_data()

DDS_ReturnCode_t DDS_DataWriter_get_matched_subscription_participant_data ( DDS_DataWriter self,
struct DDS_ParticipantBuiltinTopicData participant_data,
const DDS_InstanceHandle_t subscription_handle 
)

This operation retrieves the information on the discovered DDS_DomainParticipant associated with the subscription that is currently matching with the DDS_DataWriter.

The subscription_handle must correspond to a subscription currently associated with the DDS_DataWriter. Otherwise, the operation will fail with DDS_RETCODE_BAD_PARAMETER. The operation may also fail with DDS_RETCODE_PRECONDITION_NOT_MET if the subscription corresponds to the same DDS_DomainParticipant that the DataWriter belongs to. Use DDS_DataWriter_get_matched_subscriptions to find the subscriptions that are currently matched with the DDS_DataWriter.

Parameters
self<<in>> Cannot be NULL.
participant_data<<inout>>. The information to be filled in on the associated participant Cannot be NULL.
subscription_handle<<in>>. Handle to a specific subscription associated with the DDS_DataReader. Must correspond to a subscription currently associated with the DDS_DataWriter.

Cannot be NULL.

Returns
One of the Standard Return Codes, or DDS_RETCODE_NOT_ENABLED

◆ DDS_DataWriter_get_topic()

DDS_Topic * DDS_DataWriter_get_topic ( DDS_DataWriter self)

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.

Parameters
self<<in>> Cannot be NULL.
Returns
DDS_Topic that was used to create the DDS_DataWriter.

◆ DDS_DataWriter_get_publisher()

DDS_Publisher * DDS_DataWriter_get_publisher ( DDS_DataWriter self)

This operation returns the DDS_Publisher to which the DDS_DataWriter belongs.

Parameters
self<<in>> Cannot be NULL.
Returns
DDS_Publisher to which the DDS_DataWriter belongs.

◆ DDS_DataWriter_wait_for_acknowledgments()

DDS_ReturnCode_t DDS_DataWriter_wait_for_acknowledgments ( DDS_DataWriter self,
const struct DDS_Duration_t max_wait 
)

Blocks the calling thread until all data written by reliable DDS_DataWriter entity is acknowledged, or until timeout expires.

This operation blocks the calling thread until either all data written by the reliable DDS_DataWriter entity is acknowledged by (a) all reliable DDS_DataReader entities that are matched and alive and (b) by all required subscriptions, or until the duration specified by the max_wait parameter elapses, whichever happens first. A successful completion indicates that all the samples written have been acknowledged by all reliable matched data readers and by all required subscriptions; a timeout indicates that max_wait elapsed before all the data was acknowledged.

Note that if a thread is blocked in the call to wait_for_acknowledgments on a DataWriter and a different thread writes new samples on the same DataWriter, the new samples must be acknowledged before unblocking the thread waiting on wait_for_acknowledgments.

If the DDS_DataWriter does not have DDS_ReliabilityQosPolicy kind set to RELIABLE, this operation will complete immediately with DDS_RETCODE_OK

Parameters
self<<in>> Cannot be NULL.
max_wait<<in>> Specifies maximum time to wait for acknowledgements DDS_Duration_t .
Returns
One of the Standard Return Codes, DDS_RETCODE_NOT_ENABLED, DDS_RETCODE_TIMEOUT

◆ DDS_DataWriter_is_sample_app_acknowledged()

DDS_ReturnCode_t DDS_DataWriter_is_sample_app_acknowledged ( DDS_DataWriter self,
DDS_Boolean is_app_ack,
const struct DDS_SampleIdentity_t identity 
)

This function can be used to see if a sample has been application acknowledged.

This function can be used to see if a sample has been application acknowledged by all the matching DataReaders that were alive when the sample was written.

If a DataReader does not enable application acknowledgment (by setting DDS_ReliabilityQosPolicy::acknowledgment_kind to a value other than DDS_PROTOCOL_ACKNOWLEDGMENT_MODE), the sample is considered application acknowledged for that DataReader.

Parameters
self<<in>> Cannot be NULL.
is_app_ack<<out>> This value will be set to DDS_BOOLEAN_TRUE when the sample has been acknowledged.
identity<<in>> Sample identity.
Returns
One of the Standard Return Codes

◆ DDS_DataWriter_wait_for_asynchronous_publishing()

DDS_ReturnCode_t DDS_DataWriter_wait_for_asynchronous_publishing ( DDS_DataWriter self,
const struct DDS_Duration_t max_wait 
)

<<extension>> Blocks the calling thread until asynchronous sending is complete.

This operation blocks the calling thread (up to max_wait) until all data written by the asynchronous DDS_DataWriter is sent and acknowledged (if reliable) by all matched DDS_DataReader entities. A successful completion indicates that all the samples written have been sent and acknowledged where applicable; a time out indicates that max_wait elapsed before all the data was sent and/or acknowledged.

In other words, this guarantees that sending to best effort DDS_DataReader is complete in addition to what DDS_DataWriter_wait_for_acknowledgments provides.

If the DDS_DataWriter does not have DDS_PublishModeQosPolicy kind set to DDS_ASYNCHRONOUS_PUBLISH_MODE_QOS the operation will complete immediately with DDS_RETCODE_OK.

Parameters
self<<in>> Cannot be NULL.
max_wait<<in>> Specifies maximum time to wait for acknowledgements DDS_Duration_t .
Returns
One of the Standard Return Codes, DDS_RETCODE_NOT_ENABLED, DDS_RETCODE_TIMEOUT

◆ DDS_DataWriter_get_liveliness_lost_status()

DDS_ReturnCode_t DDS_DataWriter_get_liveliness_lost_status ( DDS_DataWriter self,
struct DDS_LivelinessLostStatus status 
)

Accesses the DDS_LIVELINESS_LOST_STATUS communication status.

This also resets the status so that it is no longer considered changed.

Parameters
self<<in>> Cannot be NULL.
status<<inout>> DDS_LivelinessLostStatus to be filled in. Cannot be NULL.
Returns
One of the Standard Return Codes

◆ DDS_DataWriter_get_offered_deadline_missed_status()

DDS_ReturnCode_t DDS_DataWriter_get_offered_deadline_missed_status ( DDS_DataWriter self,
struct DDS_OfferedDeadlineMissedStatus status 
)

Accesses the DDS_OFFERED_DEADLINE_MISSED_STATUS communication status.

This also resets the status so that it is no longer considered changed.

Parameters
self<<in>> Cannot be NULL.
status<<inout>> DDS_OfferedDeadlineMissedStatus to be filled in. Cannot be NULL.
Returns
One of the Standard Return Codes

◆ DDS_DataWriter_get_offered_incompatible_qos_status()

DDS_ReturnCode_t DDS_DataWriter_get_offered_incompatible_qos_status ( DDS_DataWriter self,
struct DDS_OfferedIncompatibleQosStatus status 
)

Accesses the DDS_OFFERED_INCOMPATIBLE_QOS_STATUS communication status.

This also resets the status so that it is no longer considered changed.

Parameters
self<<in>> Cannot be NULL.
status<<inout>> DDS_OfferedIncompatibleQosStatus to be filled in. Cannot be NULL.
Returns
One of the Standard Return Codes

◆ DDS_DataWriter_get_publication_matched_status()

DDS_ReturnCode_t DDS_DataWriter_get_publication_matched_status ( DDS_DataWriter self,
struct DDS_PublicationMatchedStatus status 
)

Accesses the DDS_PUBLICATION_MATCHED_STATUS communication status.

This also resets the status so that it is no longer considered changed.

Parameters
self<<in>> Cannot be NULL.
status<<inout>> DDS_PublicationMatchedStatus to be filled in. Cannot be NULL.
Returns
One of the Standard Return Codes

◆ DDS_DataWriter_get_reliable_writer_cache_changed_status()

DDS_ReturnCode_t DDS_DataWriter_get_reliable_writer_cache_changed_status ( DDS_DataWriter self,
struct DDS_ReliableWriterCacheChangedStatus status 
)

<<extension>> Get the reliable cache status for this writer.

This also resets the status so that it is no longer considered changed.

Parameters
self<<in>> Cannot be NULL.
status<<inout>> DDS_ReliableWriterCacheChangedStatus to be filled in. Cannot be NULL.
Returns
One of the Standard Return Codes

◆ DDS_DataWriter_get_reliable_reader_activity_changed_status()

DDS_ReturnCode_t DDS_DataWriter_get_reliable_reader_activity_changed_status ( DDS_DataWriter self,
struct DDS_ReliableReaderActivityChangedStatus status 
)

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

This also resets the status so that it is no longer considered changed.

Parameters
self<<in>> Cannot be NULL.
status<<inout>> DDS_ReliableReaderActivityChangedStatus to be filled in. Cannot be NULL.
Returns
One of the Standard Return Codes

◆ DDS_DataWriter_get_datawriter_cache_status()

DDS_ReturnCode_t DDS_DataWriter_get_datawriter_cache_status ( DDS_DataWriter self,
struct DDS_DataWriterCacheStatus status 
)

<<extension>> Get the datawriter cache status for this writer.

This also resets the status so that it is no longer considered changed.

Parameters
self<<in>> Cannot be NULL.
status<<inout>> DDS_DataWriterCacheStatus to be filled in. Cannot be NULL.
Returns
One of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.

◆ DDS_DataWriter_get_datawriter_protocol_status()

DDS_ReturnCode_t DDS_DataWriter_get_datawriter_protocol_status ( DDS_DataWriter self,
struct DDS_DataWriterProtocolStatus status 
)

<<extension>> Get the datawriter protocol status for this writer.

This also resets the status so that it is no longer considered changed.

Parameters
self<<in>> Cannot be NULL.
status<<inout>> DDS_DataWriterProtocolStatus to be filled in. Cannot be NULL.
Returns
One of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.

◆ DDS_DataWriter_get_matched_subscription_datawriter_protocol_status()

DDS_ReturnCode_t DDS_DataWriter_get_matched_subscription_datawriter_protocol_status ( DDS_DataWriter self,
struct DDS_DataWriterProtocolStatus status,
const DDS_InstanceHandle_t subscription_handle 
)

<<extension>> Get the datawriter protocol status for this writer, per matched subscription identified by the subscription_handle.

This also resets the status so that it is no longer considered changed.

Note: Status for a remote entity is only kept while the entity is alive. Once a remote entity is no longer alive, its status is deleted.

Parameters
self<<in>> Cannot be NULL.
status<<inout>> DDS_DataWriterProtocolStatus to be filled in. Cannot be NULL.
subscription_handle<<in>> Handle to a specific subscription associated with the DDS_DataReader. Cannot be NULL. Must correspond to a subscription currently associated with the DDS_DataWriter.
Returns
One of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.

◆ DDS_DataWriter_get_matched_subscription_datawriter_protocol_status_by_locator()

DDS_ReturnCode_t DDS_DataWriter_get_matched_subscription_datawriter_protocol_status_by_locator ( DDS_DataWriter self,
struct DDS_DataWriterProtocolStatus status,
const struct DDS_Locator_t locator 
)

<<extension>> Get the datawriter protocol status for this writer, per matched subscription identified by the locator.

This also resets the status so that it is no longer considered changed.

Note: Status for a remote entity is only kept while the entity is alive. Once a remote entity is no longer alive, its status is deleted.

Parameters
self<<in>> Cannot be NULL.
status<<inout>> DDS_DataWriterProtocolStatus to be filled in Cannot be NULL.
locator<<in>> Locator to a specific locator associated with the DDS_DataReader. Cannot be NULL. Must correspond to a locator of one or more subscriptions currently associated with the DDS_DataWriter.
Returns
One of the Standard Return Codes or DDS_RETCODE_NOT_ENABLED.

◆ DDS_DataWriter_get_service_request_accepted_status()

DDS_ReturnCode_t DDS_DataWriter_get_service_request_accepted_status ( DDS_DataWriter self,
struct DDS_ServiceRequestAcceptedStatus status 
)

Accesses the DDS_SERVICE_REQUEST_ACCEPTED_STATUS communication status.

This also resets the status so that it is no longer considered changed.

Parameters
self<<in>> Cannot be NULL.
status<<inout>> DDS_ServiceRequestAcceptedStatus to be filled in. Cannot be NULL.
Returns
One of the Standard Return Codes

◆ DDS_DataWriter_set_qos()

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::user_data, DDS_DataWriterQos::deadline, DDS_DataWriterQos::latency_budget, DDS_DataWriterQos::ownership_strength, DDS_DataWriterQos::transport_priority, DDS_DataWriterQos::lifespan and DDS_DataWriterQos::writer_data_lifecycle can be changed. The other policies are immutable.

Parameters
self<<in>> Cannot be NULL.
qos<<in>> The DDS_DataWriterQos to be set to. Policies must be consistent. Immutable 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)
Operations Allowed in Listener Callbacks

◆ DDS_DataWriter_set_qos_with_profile()

DDS_ReturnCode_t DDS_DataWriter_set_qos_with_profile ( DDS_DataWriter self,
const char *  library_name,
const char *  profile_name 
)

<<extension>> Change the QoS of this writer using the input XML QoS profile.

This operation modifies the QoS of the DDS_DataWriter.

The DDS_DataWriterQos::user_data, DDS_DataWriterQos::deadline, DDS_DataWriterQos::latency_budget, DDS_DataWriterQos::ownership_strength, DDS_DataWriterQos::transport_priority, DDS_DataWriterQos::lifespan and DDS_DataWriterQos::writer_data_lifecycle can be changed. The other policies are immutable.

Parameters
self<<in>> Cannot be NULL.
library_name<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDS_Publisher_set_default_library).
profile_name<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS_Publisher_set_default_profile).
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
Operations Allowed in Listener Callbacks

◆ DDS_DataWriter_get_qos()

DDS_ReturnCode_t DDS_DataWriter_get_qos ( DDS_DataWriter self,
struct DDS_DataWriterQos qos 
)

Gets the writer QoS.

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

Parameters
self<<in>> Cannot be NULL.
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_DataWriter_set_property()

DDS_ReturnCode_t DDS_DataWriter_set_property ( DDS_DataWriter self,
const char *  property_name,
const char *  value,
DDS_Boolean  propagate 
)

Set the value for a property that applies to a DataWriter.

Parameters
self<<in>> Cannot be NULL.
property_name<<in>>. Name of the property that you want to set.
value<<in>>. New value for the property.
propagate<<in>>. Indicates if the property will be propagated or not.
Returns
One of the Standard Return Codes
See also
DDS_DomainParticipant_set_property
DDS_DataReader_set_property
DDS_DomainParticipant_set_qos

◆ DDS_DataWriter_set_listener()

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

Sets the writer listener.

Parameters
self<<in>> Cannot be NULL.
l<<in>> DDS_DataWriterListener to set to
mask<<in>> DDS_StatusMask associated with the DDS_DataWriterListener. The callback function 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)

◆ DDS_DataWriter_get_listener()

struct DDS_DataWriterListener DDS_DataWriter_get_listener ( DDS_DataWriter self)

Get the writer listener.

Parameters
self<<in>> Cannot be NULL.
Returns
DDS_DataWriterListener of the DDS_DataWriter.
See also
DDS_DataWriter_get_listenerX
get_listener (abstract)

◆ DDS_DataWriter_get_listenerX()

DDS_ReturnCode_t DDS_DataWriter_get_listenerX ( DDS_DataWriter self,
struct DDS_DataWriterListener listener 
)

<<extension>> Get the writer listener.

An alternative form of get_listener that fills in an existing listener structure rather than returning one on the stack.

Parameters
self<<in>> Cannot be NULL.
listener<<inout>> DDS_DataWriterListener structure to be filled up. Cannot be NULL.
Returns
One of the Standard Return Codes
See also
DDS_DataWriter_get_listener
get_listener (abstract)

◆ DDS_DataWriter_flush()

DDS_ReturnCode_t DDS_DataWriter_flush ( DDS_DataWriter self)

<<extension>> Flushes the batch in progress in the context of the calling thread.

After being flushed, the batch is available to be sent on the network.

If the DDS_DataWriter does not have DDS_PublishModeQosPolicy kind set to DDS_ASYNCHRONOUS_PUBLISH_MODE_QOS, the batch will be sent on the network immediately (in the context of the calling thread).

If the DDS_DataWriter does have DDS_PublishModeQosPolicy kind set to DDS_ASYNCHRONOUS_PUBLISH_MODE_QOS, the batch will be sent in the context of the asynchronous publishing thread.

This operation may block in the same conditions as FooDataWriter_write.

If this operation does block, 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 fail with DDS_RETCODE_TIMEOUT.

MT Safety:
flush() is only thread-safe with batching if DDS_BatchQosPolicy::thread_safe_write is TRUE.
Parameters
self<<in>> Cannot be NULL.
Returns
One of the Standard Return Codes, DDS_RETCODE_TIMEOUT, DDS_RETCODE_OUT_OF_RESOURCES or DDS_RETCODE_NOT_ENABLED.

◆ DDS_DataWriter_take_discovery_snapshot()

DDS_ReturnCode_t DDS_DataWriter_take_discovery_snapshot ( DDS_DataWriter self,
const char *  file_name 
)

Take a snapshot of the compatible and incompatible remote readers matched by a local writer.

A possible output may be the following:

Remote readers that match the local writer domain=0 name="writerTestName"
guid="0x0101D8D1,0x20B83C0D,0x4495246E:0x80000003"
topic="FooTopic" type="FooType"
----------------------------------------------------------------------------
Compatible readers:
1. 0x0101542A,0x2C59B595,0xA1693BDF:0x80000004 name="reader1TestName"
kind="unkeyed user datareader"
unicastLocators="udpv4://192.168.1.170:7411"
liveliness="ALIVE"
Incompatible readers:
1. 0x0101542A,0x2C59B595,0xA1693BDF:0x80000104 name="reader2TestName"
kind="unkeyed user datareader"
unicastLocators="udpv4://192.168.1.170:7411"
reason="Inconsistent QoS"
----------------------------------------------------------------------------
Precondition
self is not NULL.
Parameters
self<<in>> The local writer.
file_name<<in>> Name of the file where snapshot should be printed. If NULL, the snapshot will be printed through NDDS_Config_Logger. Otherwise, the snapshot will be printed in the file specified by file_name.
Returns
One of the Standard Return Codes.