RTI Connext Java API Version 7.1.0

<<interface>> <<generic>> User data type specific data writer. More...

Inheritance diagram for FooDataWriter:
DataWriter DomainEntity Entity

Public Member Functions

InstanceHandle_t register_instance (Foo instance_data)
 Informs RTI Connext that the application will be modifying a particular instance. More...
 
InstanceHandle_t register_instance_w_timestamp (Foo instance_data, Time_t source_timestamp)
 Performs the same functions as register_instance except that the application provides the value for the source_timestamp. More...
 
InstanceHandle_t register_instance_w_params (Foo instance_data, WriteParams_t params)
 Performs the same function as com.rti.ndds.example.FooDataWriter.register_instance and com.rti.ndds.example.FooDataWriter.register_instance_w_timestamp except that it also provides the values contained in params. More...
 
void unregister_instance (Foo instance_data, InstanceHandle_t handle)
 Reverses the action of com.rti.ndds.example.FooDataWriter.register_instance. More...
 
void unregister_instance_w_timestamp (Foo instance_data, InstanceHandle_t handle, Time_t source_timestamp)
 Performs the same function as com.rti.ndds.example.FooDataWriter.unregister_instance except that it also provides the value for the source_timestamp. More...
 
void unregister_instance_w_params (Foo instance_data, WriteParams_t params)
 Performs the same function as com.rti.ndds.example.FooDataWriter.unregister_instance and com.rti.ndds.example.FooDataWriter.FooDataWriter.unregister_instance_w_timestamp except that it also provides the values contained in params. More...
 
void write (Foo instance_data, InstanceHandle_t handle)
 Modifies the value of a data instance. More...
 
void write_w_timestamp (Foo instance_data, InstanceHandle_t handle, Time_t source_timestamp)
 Performs the same function as com.rti.ndds.example.FooDataWriter.write except that it also provides the value for the source_timestamp. More...
 
void write_w_params (Foo instance_data, WriteParams_t params)
 Performs the same function as com.rti.ndds.example.FooDataWriter.write and com.rti.ndds.example.FooDataWriter.write_w_timestamp except that it also provides the values contained in params. More...
 
void dispose (Foo instance_data, InstanceHandle_t instance_handle)
 Requests the middleware to delete the instance. More...
 
void dispose_w_timestamp (Foo instance_data, InstanceHandle_t instance_handle, 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 com.rti.dds.subscription.DataReader objects by means of the source_timestamp attribute inside the com.rti.dds.subscription.SampleInfo. More...
 
void dispose_w_params (Foo instance_data, WriteParams_t params)
 Performs the same function as com.rti.ndds.example.FooDataWriter.dispose and com.rti.ndds.example.FooDataWriter.dispose_w_timestamp except that it also provides the values contained in params. More...
 
void get_key_value (Foo key_holder, InstanceHandle_t handle)
 Retrieve the instance key that corresponds to an instance handle. More...
 
InstanceHandle_t lookup_instance (Foo key_holder)
 Retrieve the instance handle that corresponds to an instance key_holder. More...
 
- Public Member Functions inherited from DataWriter
void set_qos (DataWriterQos qos)
 Sets the writer QoS. More...
 
void set_qos_with_profile (String library_name, String profile_name)
 <<extension>> Change the QoS of this writer using the input XML QoS profile. More...
 
void get_qos (DataWriterQos qos)
 Gets the writer QoS. More...
 
void set_listener (DataWriterListener l, int mask)
 Sets the writer listener. More...
 
DataWriterListener get_listener ()
 Get the writer listener. More...
 
void get_liveliness_lost_status (LivelinessLostStatus status)
 Accesses the com.rti.dds.infrastructure.StatusKind.StatusKind.LIVELINESS_LOST_STATUS communication status. More...
 
void get_offered_deadline_missed_status (OfferedDeadlineMissedStatus status)
 Accesses the com.rti.dds.infrastructure.StatusKind.StatusKind.OFFERED_DEADLINE_MISSED_STATUS communication status. More...
 
void get_offered_incompatible_qos_status (OfferedIncompatibleQosStatus status)
 Accesses the com.rti.dds.infrastructure.StatusKind.StatusKind.OFFERED_INCOMPATIBLE_QOS_STATUS communication status. More...
 
void get_publication_matched_status (PublicationMatchedStatus status)
 Accesses the com.rti.dds.infrastructure.StatusKind.StatusKind.PUBLICATION_MATCHED_STATUS communication status. More...
 
void get_reliable_writer_cache_changed_status (ReliableWriterCacheChangedStatus status)
 <<extension>> Get the reliable cache status for this writer. More...
 
void get_reliable_reader_activity_changed_status (ReliableReaderActivityChangedStatus status)
 <<extension>> Get the reliable reader activity changed status for this writer. More...
 
void get_datawriter_cache_status (DataWriterCacheStatus status)
 <<extension>> Get the datawriter cache status for this writer. More...
 
void get_datawriter_protocol_status (DataWriterProtocolStatus status)
 <<extension>> Get the datawriter protocol status for this writer. More...
 
void get_matched_subscription_datawriter_protocol_status (DataWriterProtocolStatus status, InstanceHandle_t subscription_handle)
 <<extension>> Get the datawriter protocol status for this writer, per matched subscription identified by the subscription_handle. More...
 
void get_matched_subscription_datawriter_protocol_status_by_locator (DataWriterProtocolStatus status, Locator_t locator)
 <<extension>> Get the datawriter protocol status for this writer, per matched subscription identified by the locator. More...
 
void get_service_request_accepted_status (ServiceRequestAcceptedStatus status)
 Accesses the com.rti.dds.infrastructure.StatusKind.SERVICE_REQUEST_ACCEPTED_STATUS communication status. More...
 
void get_matched_subscription_locators (LocatorSeq locators)
 <<extension>> Retrieve the list of locators for subscriptions currently "associated" with this com.rti.dds.publication.DataWriter. More...
 
void get_matched_subscriptions (InstanceHandleSeq subscription_handles)
 Retrieve the list of subscriptions currently "associated" with this com.rti.dds.publication.DataWriter. More...
 
boolean is_matched_subscription_active (InstanceHandle_t subscription_handle)
 Check if a subscription currently matched with a DataWriter is active. More...
 
void get_matched_subscription_data (SubscriptionBuiltinTopicData subscription_data, InstanceHandle_t subscription_handle)
 This operation retrieves the information on a subscription that is currently "associated" with the com.rti.dds.publication.DataWriter. More...
 
void get_matched_subscription_participant_data (ParticipantBuiltinTopicData participant_data, InstanceHandle_t subscription_handle)
 This operation retrieves the information on the discovered com.rti.dds.domain.DomainParticipant associated with the subscription that is currently matching with the com.rti.dds.publication.DataWriter. More...
 
Topic get_topic ()
 This operation returns the com.rti.dds.topic.Topic associated with the com.rti.dds.publication.DataWriter. More...
 
Publisher get_publisher ()
 This operation returns the com.rti.dds.publication.Publisher to which the com.rti.dds.publication.DataWriter belongs. More...
 
void wait_for_acknowledgments (Duration_t max_wait)
 Blocks the calling thread until all data written by reliable com.rti.dds.publication.DataWriter entity is acknowledged, or until timeout expires. More...
 
boolean is_sample_app_acknowledged (SampleIdentity_t identity)
 This method can be used to see if a sample has been application acknowledged. More...
 
void wait_for_asynchronous_publishing (Duration_t max_wait)
 <<extension>> Blocks the calling thread until asynchronous sending is complete. More...
 
void assert_liveliness ()
 This operation manually asserts the liveliness of this com.rti.dds.publication.DataWriter. More...
 
void flush ()
 <<extension>> Flushes the batch in progress in the context of the calling thread. More...
 
InstanceHandle_t register_instance_untyped (Object instance_data)
 Register a new instance with this writer. More...
 
InstanceHandle_t register_instance_w_timestamp_untyped (Object instance_data, Time_t source_timestamp)
 Register a new instance with this writer using the given time instead of the current time. More...
 
void unregister_instance_untyped (Object instance_data, InstanceHandle_t handle)
 Unregister a new instance from this writer. More...
 
void unregister_instance_w_timestamp_untyped (Object instance_data, InstanceHandle_t handle, Time_t source_timestamp)
 Unregister a new instance from this writer using the given time instead of the current time. More...
 
void write_untyped (Object instance_data, InstanceHandle_t handle)
 Publish a data sample. More...
 
void write_w_timestamp_untyped (Object instance_data, InstanceHandle_t handle, Time_t source_timestamp)
 Publish a data sample using the given time instead of the current time. More...
 
void dispose_untyped (Object instance_data, InstanceHandle_t handle)
 Dispose a data sample. More...
 
void dispose_w_timestamp_untyped (Object instance_data, InstanceHandle_t handle, Time_t source_timestamp)
 Dispose a data sample using the given time instead of the current time. More...
 
void get_key_value_untyped (Object key_holder, InstanceHandle_t handle)
 Fill in the key fields of the given data sample. More...
 
InstanceHandle_t lookup_instance_untyped (Object key_value)
 Given a sample with the given key field values, return the handle corresponding to its instance. More...
 
void take_discovery_snapshot ()
 Take a snapshot of the compatible and incompatible remote readers matched by a local writer. More...
 
void take_discovery_snapshot (String file_name)
 Take a snapshot of the compatible and incompatible remote readers matched by a local writer. More...
 
- Public Member Functions inherited from Entity
void enable ()
 Enables the com.rti.dds.infrastructure.Entity. More...
 
StatusCondition get_statuscondition ()
 Allows access to the com.rti.dds.infrastructure.StatusCondition associated with the com.rti.dds.infrastructure.Entity. More...
 
int get_status_changes ()
 Retrieves the list of communication statuses in the com.rti.dds.infrastructure.Entity that are triggered. More...
 
InstanceHandle_t get_instance_handle ()
 Allows access to the com.rti.dds.infrastructure.InstanceHandle_t associated with the com.rti.dds.infrastructure.Entity. More...
 

Detailed Description

<<interface>> <<generic>> User data type specific data writer.

Defines the user data type specific writer interface generated for each application class.

The concrete user data type writer automatically generated by the implementation is an incarnation of this class.

See also
com.rti.dds.publication.DataWriter
com.rti.ndds.example.Foo
com.rti.ndds.example.FooDataReader
the Code Generator User's Manual

Member Function Documentation

◆ register_instance()

InstanceHandle_t register_instance ( 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 com.rti.dds.infrastructure.InstanceHandle_t.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 com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL as the com.rti.dds.infrastructure.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 com.rti.ndds.example.FooDataWriter.write, com.rti.ndds.example.FooDataWriter.write_w_timestamp, com.rti.ndds.example.FooDataWriter.dispose and com.rti.ndds.example.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 com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL if com.rti.dds.infrastructure.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 com.rti.dds.publication.DataWriter has been enabled. Otherwise, com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL will be returned.

Parameters
instance_data<<in>> The instance that should be registered. Of this instance, only the fields that represent the key are examined by the function. Cannot be NULL.
Returns
For keyed data type, a handle that can be used in the calls that take a com.rti.dds.infrastructure.InstanceHandle_t, such as write, dispose, unregister_instance, or return com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL on failure. If the instance_data is of a data type that has no keys, this function always returns com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL.
See also
com.rti.ndds.example.FooDataWriter.unregister_instance, com.rti.ndds.example.FooDataWriter.get_key_value, Relationship between registration, liveliness and ownership

References DataWriter.register_instance_untyped().

◆ register_instance_w_timestamp()

InstanceHandle_t register_instance_w_timestamp ( Foo  instance_data,
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 com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL if com.rti.dds.infrastructure.ResourceLimitsQosPolicy.max_instances limit has been exceeded.

This operation can only be called after com.rti.dds.publication.DataWriter has been enabled. Otherwise, com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL will be returned.

Parameters
instance_data<<in>> The instance that should be registered. Of this instance, only the fields that represent the key are examined by the function. Cannot be NULL.
source_timestamp<<in>> The timestamp value must be greater than or equal to the timestamp value used in the last writer operation (used in a register, unregister, dispose, or write, with either the automatically supplied timestamp or the application provided timestamp). This timestamp may potentially affect the order in which readers observe events from multiple writers. Cannot be NULL.
Returns
For keyed data type, return a handle that can be used in the calls that take a com.rti.dds.infrastructure.InstanceHandle_t, such as write, dispose, unregister_instance, or return com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL on failure. If the instance_data is of a data type that has no keys, this function always return com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL.
See also
com.rti.ndds.example.FooDataWriter.unregister_instance, com.rti.ndds.example.FooDataWriter.get_key_value

References DataWriter.register_instance_w_timestamp_untyped().

◆ register_instance_w_params()

InstanceHandle_t register_instance_w_params ( Foo  instance_data,
WriteParams_t  params 
)

◆ unregister_instance()

void unregister_instance ( Foo  instance_data,
InstanceHandle_t  handle 
)

Reverses the action of com.rti.ndds.example.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 com.rti.ndds.example.FooDataWriter.register_instance. Otherwise, this operation may fail with com.rti.dds.infrastructure.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 com.rti.dds.publication.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 com.rti.dds.infrastructure.InstanceHandle_t.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 com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL, then it must correspond to an instance that has been registered. If there is no correspondence, the operation will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER.

RTI Connext will not detect the error when the handle is any value other than com.rti.dds.infrastructure.InstanceHandle_t.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 com.rti.ndds.example.FooDataWriter.unregister_instance, the application wants to modify (com.rti.ndds.example.FooDataWriter.write or com.rti.ndds.example.FooDataWriter.dispose) an instance, it has to register it again, or else use the special handle value com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL.

This operation does not indicate that the instance is deleted (that is the purpose of com.rti.ndds.example.FooDataWriter.dispose). The operation com.rti.ndds.example.FooDataWriter.unregister_instance just indicates that the com.rti.dds.publication.DataWriter no longer has anything to say about the instance. com.rti.dds.subscription.DataReader entities that are reading the instance may receive a sample with com.rti.dds.subscription.InstanceStateKind.NOT_ALIVE_NO_WRITERS_INSTANCE_STATE for the instance, unless there are other com.rti.dds.publication.DataWriter objects writing that same instance.

com.rti.dds.infrastructure.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 com.rti.dds.publication.DataWriter was the exclusive owner of the instance, then calling unregister_instance() will relinquish that ownership.

If com.rti.dds.infrastructure.ReliabilityQosPolicy.kind is set to com.rti.dds.infrastructure.ReliabilityQosPolicyKind.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 com.rti.dds.infrastructure.ReliabilityQosPolicy.max_blocking_time; if this writer is still unable to unregister after that period, this method will fail with com.rti.dds.infrastructure.RETCODE_TIMEOUT.

Parameters
instance_data<<in>> The instance that should be unregistered. If com.rti.ndds.example.Foo has a key and instance_handle is com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL, only the fields that represent the key are examined by the function. Otherwise, instance_data is not used. If instance_data is used, it must represent an instance that has been registerd. Otherwise, this method may fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER . If com.rti.ndds.example.Foo has a key, instance_data can be NULL only if handle is not com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL. Otherwise, this method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER.
handle<<in>> represents the instance to be unregistered. If com.rti.ndds.example.Foo has a key and handle is com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL, handle is not used and instance is deduced from instance_data. If com.rti.ndds.example.Foo has no key, handle is not used. If handle is used, it must represent an instance that has been registered. Otherwise, this method may fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER. This method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if handle is NULL. If com.rti.ndds.example.Foo has a key, handle cannot be com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL if instance_data is NULL. Otherwise, this method will report the error com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER.
Exceptions
Oneof the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_TIMEOUT or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED
See also
com.rti.ndds.example.FooDataWriter.register_instance
com.rti.ndds.example.FooDataWriter.FooDataWriter.unregister_instance_w_timestamp
com.rti.ndds.example.FooDataWriter.get_key_value
Relationship between registration, liveliness and ownership

References DataWriter.unregister_instance_untyped().

◆ unregister_instance_w_timestamp()

void unregister_instance_w_timestamp ( Foo  instance_data,
InstanceHandle_t  handle,
Time_t  source_timestamp 
)

Performs the same function as com.rti.ndds.example.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 com.rti.ndds.example.FooDataWriter.unregister_instance operation.

This operation may block and may time out (com.rti.dds.infrastructure.RETCODE_TIMEOUT) under the same circumtances described for the unregister_instance operation.

Parameters
instance_data<<in>> The instance that should be unregistered. If com.rti.ndds.example.Foo has a key and instance_handle is com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL, only the fields that represent the key are examined by the function. Otherwise, instance_data is not used. If instance_data is used, it must represent an instance that has been registerd. Otherwise, this method may fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER. If com.rti.ndds.example.Foo has a key, instance_data can be NULL only if handle is not com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL. Otherwise, this method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER.
handle<<in>> represents the instance to be unregistered. If com.rti.ndds.example.Foo has a key and handle is com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL, handle is not used and instance is deduced from instance_data. If com.rti.ndds.example.Foo has no key, handle is not used. If handle is used, it must represent an instance that has been registered. Otherwise, this method may fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER. This method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if handle is NULL. If com.rti.ndds.example.Foo has a key, handle cannot be com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL if instance_data is NULL. Otherwise, this method will report the error com.rti.dds.infrastructure.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.
Exceptions
Oneof the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_TIMEOUT or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.
See also
com.rti.ndds.example.FooDataWriter.register_instance
com.rti.ndds.example.FooDataWriter.unregister_instance
com.rti.ndds.example.FooDataWriter.get_key_value

References DataWriter.unregister_instance_w_timestamp_untyped().

◆ unregister_instance_w_params()

void unregister_instance_w_params ( Foo  instance_data,
WriteParams_t  params 
)

Performs the same function as com.rti.ndds.example.FooDataWriter.unregister_instance and com.rti.ndds.example.FooDataWriter.FooDataWriter.unregister_instance_w_timestamp except that it also provides the values contained in params.

See also
com.rti.ndds.example.FooDataWriter.write_w_params
com.rti.ndds.example.FooDataWriter.dispose_w_params

◆ write()

void write ( Foo  instance_data,
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 com.rti.dds.subscription.DataReader objects by means of the source_timestamp attribute inside the com.rti.dds.subscription.SampleInfo. (Refer to com.rti.dds.subscription.SampleInfo and DESTINATION_ORDER QoS policy for details).

As a side effect, this operation asserts liveliness on the com.rti.dds.publication.DataWriter itself, the com.rti.dds.publication.Publisher and the com.rti.dds.domain.DomainParticipant.

Note that the special value com.rti.dds.infrastructure.InstanceHandle_t.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 com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL, then it must correspond to an instance that has been registered. If there is no correspondence, the operation will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER.

RTI Connext will not detect the error when the handle is any value other than com.rti.dds.infrastructure.InstanceHandle_t.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 com.rti.dds.infrastructure.ReliabilityQosPolicyKind.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 com.rti.dds.infrastructure.ReliabilityQosPolicyKind.BEST_EFFORT_RELIABILITY_QOS and com.rti.dds.infrastructure.PublishModeQosPolicyKind.PublishModeQosPolicyKind.ASYNCHRONOUS_PUBLISH_MODE_QOS. In this case, the com.rti.dds.publication.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 com.rti.dds.infrastructure.HistoryQosPolicy. If the asynchronous thread does not send DDS samples fast enough (such as when using a slow com.rti.dds.publication.FlowController, the queue may fill up. In that case, subsequent write calls will block.

If com.rti.dds.infrastructure.ReliabilityQosPolicy.max_blocking_time elapses before the com.rti.dds.publication.DataWriter can store the modification without exceeding the limits, the operation will fail and return com.rti.dds.infrastructure.RETCODE_TIMEOUT for KEEP_ALL configurations.

Here is how the write operation behaves when com.rti.dds.infrastructure.HistoryQosPolicyKind.HistoryQosPolicyKind.KEEP_LAST_HISTORY_QOS and com.rti.dds.infrastructure.ReliabilityQosPolicyKind.RELIABLE_RELIABILITY_QOS are used:

Here is how the write operation behaves when com.rti.dds.infrastructure.HistoryQosPolicyKind.HistoryQosPolicyKind.KEEP_ALL_HISTORY_QOS and com.rti.dds.infrastructure.ReliabilityQosPolicyKind.RELIABLE_RELIABILITY_QOS are used:

If there are no instance resources left, this operation may fail with com.rti.dds.infrastructure.RETCODE_OUT_OF_RESOURCES. Calling com.rti.ndds.example.FooDataWriter.unregister_instance may help freeing up some resources.

This operation will fail with com.rti.dds.infrastructure.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).

See com.rti.dds.infrastructure.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 com.rti.dds.infrastructure.ResourceLimitsQosPolicy.max_samples or com.rti.dds.infrastructure.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 com.rti.dds.infrastructure.ReliabilityQosPolicy.max_blocking_time.

Parameters
instance_data<<in>> The data to write.

This method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if instance_data is NULL.

Parameters
handle<<in>> Either the handle returned by a previous call to com.rti.ndds.example.FooDataWriter.register_instance, or else the special value com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL. If com.rti.ndds.example.Foo has a key and handle is not com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL, handle must represent a registered instance of type com.rti.ndds.example.Foo. Otherwise, this method may fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER.
Exceptions
Oneof the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_TIMEOUT, com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET, com.rti.dds.infrastructure.RETCODE_OUT_OF_RESOURCES, or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.
MT Safety:
It is UNSAFE to modify instance_data before the operation has finished. The operation is otherwise SAFE.
See also
com.rti.dds.subscription.DataReader
com.rti.ndds.example.FooDataWriter.write_w_timestamp
DESTINATION_ORDER

References DataWriter.write_untyped().

◆ write_w_timestamp()

void write_w_timestamp ( Foo  instance_data,
InstanceHandle_t  handle,
Time_t  source_timestamp 
)

Performs the same function as com.rti.ndds.example.FooDataWriter.write except that it also provides the value for the source_timestamp.

Explicitly provides the timestamp that will be available to the com.rti.dds.subscription.DataReader objects by means of the source_timestamp attribute inside the com.rti.dds.subscription.SampleInfo. (Refer to com.rti.dds.subscription.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 com.rti.ndds.example.FooDataWriter.write operation.

This operation may block and time out (com.rti.dds.infrastructure.RETCODE_TIMEOUT) under the same circumtances described for com.rti.ndds.example.FooDataWriter.write.

If there are no instance resources left, this operation may fail with com.rti.dds.infrastructure.RETCODE_OUT_OF_RESOURCES. Calling com.rti.ndds.example.FooDataWriter.unregister_instance may help free up some resources.

This operation may fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER under the same circumstances described for the write operation.

Parameters
instance_data<<in>> The data to write. This method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if instance_data is NULL.
handle<<in>> Either the handle returned by a previous call to com.rti.ndds.example.FooDataWriter.register_instance, or else the special value com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL. If com.rti.ndds.example.Foo has a key and handle is not com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL, handle must represent a registered instance of type com.rti.ndds.example.Foo. Otherwise, this method may fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER. This method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if handle is NULL.
source_timestamp<<in>> When using com.rti.dds.infrastructure.DestinationOrderQosPolicyKind.DestinationOrderQosPolicyKind.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 com.rti.dds.infrastructure.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 com.rti.dds.infrastructure.DestinationOrderQosPolicy.source_timestamp_tolerance, the function will return com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER.

Cannot be NULL.

Exceptions
Oneof the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_TIMEOUT, com.rti.dds.infrastructure.RETCODE_OUT_OF_RESOURCES, or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.
See also
com.rti.ndds.example.FooDataWriter.write
com.rti.dds.subscription.DataReader
DESTINATION_ORDER

References DataWriter.write_w_timestamp_untyped().

◆ write_w_params()

void write_w_params ( Foo  instance_data,
WriteParams_t  params 
)

Performs the same function as com.rti.ndds.example.FooDataWriter.write and com.rti.ndds.example.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 (com.rti.dds.infrastructure.RETCODE_TIMEOUT) under the same circumstances described for com.rti.ndds.example.FooDataWriter.write.

If there are no instance resources left, this operation may fail with com.rti.dds.infrastructure.RETCODE_OUT_OF_RESOURCES. Calling com.rti.ndds.example.FooDataWriter.unregister_instance_w_params may help free up some resources.

This operation may fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER under the same circumstances described for the com.rti.ndds.example.FooDataWriter.write.

Parameters
instance_data<<in>> The data to write. This method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if instance_data is NULL.
params<<inout>> The write parameters. Note that this is an inout parameter if you activate com.rti.dds.infrastructure.WriteParams_t.replace_auto; otherwise it won't be modified. This method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if params is NULL.
Exceptions
Oneof the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_TIMEOUT, com.rti.dds.infrastructure.RETCODE_OUT_OF_RESOURCES or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.
See also
com.rti.ndds.example.FooDataWriter.write
com.rti.dds.subscription.DataReader

◆ dispose()

void dispose ( Foo  instance_data,
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 com.rti.dds.publication.DataWriter communicates this state change to com.rti.dds.subscription.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 com.rti.dds.subscription.SampleInfo.instance_state. Disposed instances have the value com.rti.dds.subscription.InstanceStateKind.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 com.rti.dds.infrastructure.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 com.rti.dds.infrastructure.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 com.rti.dds.subscription.DataReader objects by means of the source_timestamp attribute inside the com.rti.dds.subscription.SampleInfo.

The constraints on the values of the handle parameter and the corresponding error behavior are the same specified for the com.rti.ndds.example.FooDataWriter.unregister_instance operation.

The special value com.rti.dds.infrastructure.InstanceHandle_t.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 com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL, then it must correspond to an instance that has been registered. If there is no correspondence, the operation will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER.

RTI Connext will not detect the error when the instance_handle is any value other than com.rti.dds.infrastructure.InstanceHandle_t.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 (com.rti.dds.infrastructure.RETCODE_TIMEOUT) under the same circumstances described for com.rti.ndds.example.FooDataWriter.write.

If there are no instance resources left, this operation may fail with com.rti.dds.infrastructure.RETCODE_OUT_OF_RESOURCES. Calling com.rti.ndds.example.FooDataWriter.unregister_instance may help free up some resources.

Parameters
instance_data<<in>> The data to dispose. If com.rti.ndds.example.Foo has a key and instance_handle is com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL, only the fields that represent the key are examined by the function. Otherwise, instance_data is not used. If com.rti.ndds.example.Foo has a key, instance_data can be NULL only if instance_handle is not com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL. Otherwise, this method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER.
instance_handle<<in>> Either the handle returned by a previous call to com.rti.ndds.example.FooDataWriter.register_instance, or else the special value com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL. If com.rti.ndds.example.Foo has a key and instance_handle is com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL, instance_handle is not used and it is deduced from instance_data. If com.rti.ndds.example.Foo has no key, instance_handle is not used. If instance_handle is used, it must represent an instance of type com.rti.ndds.example.Foo that has been written or registered with this writer. Otherwise, this method fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER. This method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if instance_handle is NULL. If com.rti.ndds.example.Foo has a key, instance_handle cannot be com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL if instance_data is NULL. Otherwise, this method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER.
Exceptions
Oneof the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_TIMEOUT, com.rti.dds.infrastructure.RETCODE_OUT_OF_RESOURCES or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.
See also
com.rti.ndds.example.FooDataWriter.dispose_w_timestamp
Relationship between registration, liveliness and ownership

References DataWriter.dispose_untyped().

◆ dispose_w_timestamp()

void dispose_w_timestamp ( Foo  instance_data,
InstanceHandle_t  instance_handle,
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 com.rti.dds.subscription.DataReader objects by means of the source_timestamp attribute inside the com.rti.dds.subscription.SampleInfo.

The constraints on the values of the handle parameter and the corresponding error behavior are the same specified for the com.rti.ndds.example.FooDataWriter.dispose operation.

This operation may block and time out (com.rti.dds.infrastructure.RETCODE_TIMEOUT) under the same circumtances described for com.rti.ndds.example.FooDataWriter.write.

If there are no instance resources left, this operation may fail with com.rti.dds.infrastructure.RETCODE_OUT_OF_RESOURCES. Calling com.rti.ndds.example.FooDataWriter.unregister_instance may help freeing up some resources.

Parameters
instance_data<<in>> The data to dispose. If com.rti.ndds.example.Foo has a key and instance_handle is com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL, only the fields that represent the key are examined by the function. Otherwise, instance_data is not used. If com.rti.ndds.example.Foo has a key, instance_data can be NULL only if instance_handle is not com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL. Otherwise, this method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER.
instance_handle<<in>> Either the handle returned by a previous call to com.rti.ndds.example.FooDataWriter.register_instance, or else the special value com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL. If com.rti.ndds.example.Foo has a key and handle is not com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL, handle must represent a registered instance of type com.rti.ndds.example.Foo. Otherwise, this method may fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER. This method will fail with com.rti.dds.infrastructure.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 com.rti.dds.subscription.DataReader objects by means of the source_timestamp attribute inside the com.rti.dds.subscription.SampleInfo. Cannot be NULL.
Exceptions
Oneof the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_TIMEOUT, com.rti.dds.infrastructure.RETCODE_OUT_OF_RESOURCES or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.
See also
com.rti.ndds.example.FooDataWriter.dispose

References DataWriter.dispose_w_timestamp_untyped().

◆ dispose_w_params()

void dispose_w_params ( Foo  instance_data,
WriteParams_t  params 
)

Performs the same function as com.rti.ndds.example.FooDataWriter.dispose and com.rti.ndds.example.FooDataWriter.dispose_w_timestamp except that it also provides the values contained in params.

See also
com.rti.ndds.example.FooDataWriter.write_w_params

◆ get_key_value()

void get_key_value ( Foo  key_holder,
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 method has no effect and exits with no error.

For keyed data types, this operation may fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if the handle does not correspond to an existing data-object known to the com.rti.dds.publication.DataWriter.

Parameters
key_holder<<inout>> a user data type specific key holder, whose key fields are filled by this operation. If com.rti.ndds.example.Foo has no key, this method has no effect.

This method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if key_holder is NULL.

Parameters
handle<<in>> the instance whose key is to be retrieved. If com.rti.ndds.example.Foo has a key, handle must represent a registered instance of type com.rti.ndds.example.Foo. Otherwise, this method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER. If com.rti.ndds.example.Foo has a key and handle is com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL, this method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER. This method will fail with com.rti.dds.infrastructure.RETCODE_BAD_PARAMETER if handle is NULL.
Exceptions
Oneof the Standard Return Codes or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.
See also
com.rti.ndds.example.FooDataReader.get_key_value

References DataWriter.get_key_value_untyped().

◆ lookup_instance()

InstanceHandle_t lookup_instance ( 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
key_holder<<in>> a user data type specific key holder.
Returns
the instance handle associated with this instance. If com.rti.ndds.example.Foo has no key, this method has no effect and returns com.rti.dds.infrastructure.InstanceHandle_t.HANDLE_NIL

References DataWriter.lookup_instance_untyped().