FooDataWriter Class Reference
[Data Writers]

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

Inheritance diagram for FooDataWriter:

List of all members.

Public Member Functions
InstanceHandle_t	register_instance (Foo instance_data)
	Informs RTI Connext that the application will be modifying a particular instance.
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.
InstanceHandle_t	register_instance_w_params (Foo instance_data, WriteParams_t params)
	Performs the same function as com.rti.dds.topic.example.FooDataWriter.register_instance and com.rti.dds.topic.example.FooDataWriter.register_instance_w_timestamp except that it also provides the values contained in params.
void	unregister_instance (Foo instance_data, InstanceHandle_t handle)
	Reverses the action of com.rti.dds.topic.example.FooDataWriter.register_instance.
void	unregister_instance_w_timestamp (Foo instance_data, InstanceHandle_t handle, Time_t source_timestamp)
	Performs the same function as com.rti.dds.topic.example.FooDataWriter.unregister_instance except that it also provides the value for the source_timestamp.
void	unregister_instance_w_params (Foo instance_data, WriteParams_t params)
	Performs the same function as com.rti.dds.topic.example.FooDataWriter.unregister_instance and FooDataWriter.unregister_instance_w_timestamp except that it also provides the values contained in params.
void	write (Foo instance_data, InstanceHandle_t handle)
	Modifies the value of a data instance.
void	write_w_timestamp (Foo instance_data, InstanceHandle_t handle, Time_t source_timestamp)
	Performs the same function as com.rti.dds.topic.example.FooDataWriter.write except that it also provides the value for the source_timestamp.
void	write_w_params (Foo instance_data, WriteParams_t params)
	Performs the same function as com.rti.dds.topic.example.FooDataWriter.write and com.rti.dds.topic.example.FooDataWriter.write_w_timestamp except that it also provides the values contained in params.
void	dispose (Foo instance_data, InstanceHandle_t instance_handle)
	Requests the middleware to delete the data.
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.
void	dispose_w_params (Foo instance_data, WriteParams_t params)
	Performs the same function as com.rti.dds.topic.example.FooDataWriter.dispose and com.rti.dds.topic.example.FooDataWriter.dispose_w_timestamp except that it also provides the values contained in params.
void	get_key_value (Foo key_holder, InstanceHandle_t handle)
	Retrieve the instance key that corresponds to an instance handle.
InstanceHandle_t	lookup_instance (Foo key_holder)
	Retrieve the instance handle that corresponds to an instance key_holder.

---

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

Foo

com.rti.dds.topic.example.FooDataReader

rtiddsgen

---

Member Function Documentation

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 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 InstanceHandle_t.HANDLE_NIL as the com.rti.dds.infrastructure.InstanceHandle_t paramater 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.dds.topic.example.FooDataWriter.write, com.rti.dds.topic.example.FooDataWriter.write_w_timestamp, com.rti.dds.topic.example.FooDataWriter.dispose and com.rti.dds.topic.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 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, 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 InstanceHandle_t.HANDLE_NIL on failure. If the instance_data is of a data type that has no keys, this function always return InstanceHandle_t.HANDLE_NIL.

See also:

com.rti.dds.topic.example.FooDataWriter.unregister_instance, com.rti.dds.topic.example.FooDataWriter.get_key_value, RELATIONSHIP BETWEEN REGISTRATION, LIVELINESS and OWNERSHIP

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 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, 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 InstanceHandle_t.HANDLE_NIL on failure. If the instance_data is of a data type that has no keys, this function always return InstanceHandle_t.HANDLE_NIL.

See also:

com.rti.dds.topic.example.FooDataWriter.unregister_instance, com.rti.dds.topic.example.FooDataWriter.get_key_value

InstanceHandle_t register_instance_w_params	(	Foo	instance_data,
		WriteParams_t	params
	)

Performs the same function as com.rti.dds.topic.example.FooDataWriter.register_instance and com.rti.dds.topic.example.FooDataWriter.register_instance_w_timestamp except that it also provides the values contained in params.

void unregister_instance	(	Foo	instance_data,
		InstanceHandle_t	handle
	)

Reverses the action of com.rti.dds.topic.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.dds.topic.example.FooDataWriter.register_instance. Otherwise, this operation may fail with 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 com.rti.dds.topic.example.FooDataWriter.unregister_instance().

The special value 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 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 RETCODE_BAD_PARAMETER.

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

This operation does not indicate that the instance is deleted (that is the purpose of com.rti.dds.topic.example.FooDataWriter.dispose). The operation com.rti.dds.topic.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 InstanceStateKind.NOT_ALIVE_NO_WRITERS_INSTANCE_STATE for the instance, unless there are other com.rti.dds.publication.DataWriter objects writing that same instance.

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

Parameters:

	instance_data	<<in>> The instance that should be unregistered. If Foo has a key and instance_handle is 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 RETCODE_BAD_PARAMETER . If Foo has a key, instance_data can be NULL only if handle is not InstanceHandle_t.HANDLE_NIL. Otherwise, this method will fail with RETCODE_BAD_PARAMETER.
	handle	<<in>> represents the instance to be unregistered. If Foo has a key and handle is InstanceHandle_t.HANDLE_NIL, handle is not used and instance is deduced from instance_data. If Foo has no key, handle is not used. If handle is used, it must represent an instance that has been registered. Otherwise, this method may fail with RETCODE_BAD_PARAMETER. This method will fail with RETCODE_BAD_PARAMETER if handle is NULL. If Foo has a key, handle cannot be InstanceHandle_t.HANDLE_NIL if instance_data is NULL. Otherwise, this method will report the error RETCODE_BAD_PARAMETER.

Exceptions:

One

of the Standard Return Codes, RETCODE_TIMEOUT or RETCODE_NOT_ENABLED

See also:

com.rti.dds.topic.example.FooDataWriter.register_instance

FooDataWriter.unregister_instance_w_timestamp

com.rti.dds.topic.example.FooDataWriter.get_key_value

RELATIONSHIP BETWEEN REGISTRATION, LIVELINESS and OWNERSHIP

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

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

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

Parameters:

	instance_data	<<in>> The instance that should be unregistered. If Foo has a key and instance_handle is 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 RETCODE_BAD_PARAMETER. If Foo has a key, instance_data can be NULL only if handle is not InstanceHandle_t.HANDLE_NIL. Otherwise, this method will fail with RETCODE_BAD_PARAMETER.
	handle	<<in>> represents the instance to be unregistered. If Foo has a key and handle is InstanceHandle_t.HANDLE_NIL, handle is not used and instance is deduced from instance_data. If Foo has no key, handle is not used. If handle is used, it must represent an instance that has been registered. Otherwise, this method may fail with RETCODE_BAD_PARAMETER. This method will fail with RETCODE_BAD_PARAMETER if handle is NULL. If Foo has a key, handle cannot be InstanceHandle_t.HANDLE_NIL if instance_data is NULL. Otherwise, this method will fail with 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:

One

of the Standard Return Codes, RETCODE_TIMEOUT or RETCODE_NOT_ENABLED.

See also:

com.rti.dds.topic.example.FooDataWriter.register_instance

com.rti.dds.topic.example.FooDataWriter.unregister_instance

com.rti.dds.topic.example.FooDataWriter.get_key_value

void unregister_instance_w_params	(	Foo	instance_data,
		WriteParams_t	params
	)

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

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

RTI Connext will not detect the error when the handle is any value other than 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 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.

Specifically, this operation may block in the following situations (note that the list may not be exhaustive), even if its com.rti.dds.infrastructure.HistoryQosPolicyKind is HistoryQosPolicyKind.KEEP_LAST_HISTORY_QOS:

• If (com.rti.dds.infrastructure.ResourceLimitsQosPolicy.max_samples < com.rti.dds.infrastructure.ResourceLimitsQosPolicy.max_instances * com.rti.dds.infrastructure.HistoryQosPolicy.depth), then in the situation where the max_samples resource limit is exhausted, RTI Connext is allowed to discard samples of some other instance, as long as at least one sample remains for such an instance. If it is still not possible to make space available to store the modification, the writer is allowed to block.
• If (com.rti.dds.infrastructure.ResourceLimitsQosPolicy.max_samples < com.rti.dds.infrastructure.ResourceLimitsQosPolicy.max_instances), then the DataWriter may block regardless of the com.rti.dds.infrastructure.HistoryQosPolicy.depth.
• If (com.rti.dds.infrastructure.RtpsReliableWriterProtocol_t.min_send_window_size < com.rti.dds.infrastructure.ResourceLimitsQosPolicy.max_samples), then it is possible for the send_window_size limit to be reached before RTI Connext is allowed to discard samples, in which case the com.rti.dds.publication.DataWriter will block.

This operation may also block when using ReliabilityQosPolicyKind.BEST_EFFORT_RELIABILITY_QOS and PublishModeQosPolicyKind.ASYNCHRONOUS_PUBLISH_MODE_QOS. In this case, the com.rti.dds.publication.DataWriter will queue samples until they are sent by the asynchronous publishing thread. The number of samples that can be stored is determined by the com.rti.dds.infrastructure.HistoryQosPolicy. If the asynchronous thread does not send samples fast enough (e.g., when using a slow com.rti.dds.publication.FlowController), the queue may fill up. In that case, subsequent write calls will block.

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

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

This operation will fail with 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).

Parameters:

instance_data

<<in>> The data to write.

This method will fail with RETCODE_BAD_PARAMETER if instance_data is NULL.

Parameters:

handle

<<in>> Either the handle returned by a previous call to com.rti.dds.topic.example.FooDataWriter.register_instance, or else the special value InstanceHandle_t.HANDLE_NIL. If Foo has a key and handle is not InstanceHandle_t.HANDLE_NIL, handle must represent a registered instance of type Foo. Otherwise, this method may fail with RETCODE_BAD_PARAMETER. This method will fail with RETCODE_BAD_PARAMETER if handle is NULL.

Exceptions:

One

of the Standard Return Codes, RETCODE_TIMEOUT, RETCODE_PRECONDITION_NOT_MET, RETCODE_OUT_OF_RESOURCES, or RETCODE_NOT_ENABLED.

See also:

com.rti.dds.subscription.DataReader

com.rti.dds.topic.example.FooDataWriter.write_w_timestamp

DESTINATION_ORDER

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

Performs the same function as com.rti.dds.topic.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.dds.topic.example.FooDataWriter.write operation.

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

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

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

Cannot be NULL.

Exceptions:

One

of the Standard Return Codes, RETCODE_TIMEOUT, RETCODE_OUT_OF_RESOURCES, or RETCODE_NOT_ENABLED.

See also:

com.rti.dds.topic.example.FooDataWriter.write

com.rti.dds.subscription.DataReader

DESTINATION_ORDER

void write_w_params	(	Foo	instance_data,
		WriteParams_t	params
	)

Performs the same function as com.rti.dds.topic.example.FooDataWriter.write and com.rti.dds.topic.example.FooDataWriter.write_w_timestamp except that it also provides the values contained in params.

Allows provision of the instance handle, source timestamp, publication priority, and cookie, in params.

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

The cookie is a sequence of bytes tagging the data being written, and is used to retrieve the data when it is not available to the writer when needed.

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

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

This operation may fail with 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 RETCODE_BAD_PARAMETER if instance_data is NULL.
	params	<<in>>

The handle is either returned by a previous call to com.rti.dds.topic.example.FooDataWriter.register_instance, or else the special value InstanceHandle_t.HANDLE_NIL. If Foo has a key and handle is not InstanceHandle_t.HANDLE_NIL, handle must represent a registered instance of type Foo. Otherwise, this method may fail with RETCODE_BAD_PARAMETER. This method will fail with RETCODE_BAD_PARAMETER if handle is NULL.

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

Exceptions:

One

of the Standard Return Codes, RETCODE_TIMEOUT, RETCODE_OUT_OF_RESOURCES or RETCODE_NOT_ENABLED.

See also:

com.rti.dds.topic.example.FooDataWriter.write

com.rti.dds.subscription.DataReader

DESTINATION_ORDER

void dispose	(	Foo	instance_data,
		InstanceHandle_t	instance_handle
	)

Requests the middleware to delete the data.

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

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

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

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

When this operation is used, RTI Connext 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.dds.topic.example.FooDataWriter.unregister_instance operation.

The special value 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 handle is any value other than 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 RETCODE_BAD_PARAMETER.

RTI Connext will not detect the error when the handle is any value other than 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 dispose() operation is for the instance as indicated by the handle.

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

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

Parameters:

	instance_data	<<in>> The data to dispose. If Foo has a key and instance_handle is InstanceHandle_t.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 InstanceHandle_t.HANDLE_NIL. Otherwise, this method will fail with RETCODE_BAD_PARAMETER.
	instance_handle	<<in>> Either the handle returned by a previous call to com.rti.dds.topic.example.FooDataWriter.register_instance, or else the special value InstanceHandle_t.HANDLE_NIL. If Foo has a key and instance_handle is InstanceHandle_t.HANDLE_NIL, instance_handle is not used and instance is deduced from instance_data. If Foo has no key, instance_handle is not used. If handle is used, it must represent a registered instance of type Foo. Otherwise, this method fail with RETCODE_BAD_PARAMETER. This method will fail with RETCODE_BAD_PARAMETER if handle is NULL. If Foo has a key, instance_handle cannot be InstanceHandle_t.HANDLE_NIL if instance_data is NULL. Otherwise, this method will fail with RETCODE_BAD_PARAMETER.

Exceptions:

One

of the Standard Return Codes, RETCODE_TIMEOUT, RETCODE_OUT_OF_RESOURCES or RETCODE_NOT_ENABLED.

See also:

com.rti.dds.topic.example.FooDataWriter.dispose_w_timestamp

RELATIONSHIP BETWEEN REGISTRATION, LIVELINESS and OWNERSHIP

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.dds.topic.example.FooDataWriter.dispose operation.

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

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

Parameters:

	instance_data	<<in>> The data to dispose. If Foo has a key and instance_handle is InstanceHandle_t.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 InstanceHandle_t.HANDLE_NIL. Otherwise, this method will fail with RETCODE_BAD_PARAMETER.
	instance_handle	<<in>> Either the handle returned by a previous call to com.rti.dds.topic.example.FooDataWriter.register_instance, or else the special value InstanceHandle_t.HANDLE_NIL. If Foo has a key and instance_handle is InstanceHandle_t.HANDLE_NIL, instance_handle is not used and instance is deduced from instance_data. If Foo has no key, instance_handle is not used. If handle is used, it must represent a registered instance of type Foo. Otherwise, this method may fail with RETCODE_BAD_PARAMETER This method will fail with RETCODE_BAD_PARAMETER if handle is NULL. If Foo has a key, instance_handle cannot be InstanceHandle_t.HANDLE_NIL if instance_data is NULL. Otherwise, this method will fail with RETCODE_BAD_PARAMETER.
	source_timestamp	<<in>> The timestamp value must be greater than or equal to the timestamp value used in the last writer operation (used in a register, unregister, dispose, or write, with either the automatically supplied timestamp or the application provided timestamp). This timestamp may potentially affect the order in which readers observe events from multiple writers. This timestamp will be available to the com.rti.dds.subscription.DataReader objects by means of the source_timestamp attribute inside the com.rti.dds.subscription.SampleInfo. Cannot be NULL.

Exceptions:

One

of the Standard Return Codes, RETCODE_TIMEOUT, RETCODE_OUT_OF_RESOURCES or RETCODE_NOT_ENABLED.

See also:

com.rti.dds.topic.example.FooDataWriter.dispose

void dispose_w_params	(	Foo	instance_data,
		WriteParams_t	params
	)

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

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 Foo has no key, this method has no effect and exit with no error.

For keyed data types, this operation may fail with 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 Foo has no key, this method has no effect. This method will fail with RETCODE_BAD_PARAMETER if key_holder is NULL.
	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 method will fail with RETCODE_BAD_PARAMETER. If Foo has a key and handle is InstanceHandle_t.HANDLE_NIL, this method will fail with RETCODE_BAD_PARAMETER. This method will fail with RETCODE_BAD_PARAMETER if handle is NULL.

Exceptions:

One

of the Standard Return Codes or RETCODE_NOT_ENABLED.

See also:

com.rti.dds.topic.example.FooDataReader.get_key_value

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 Foo has no key, this method has no effect and returns InstanceHandle_t.HANDLE_NIL