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.

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, Registration_liveliness_ownership

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.

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, Registration_liveliness_ownership

The provided source_timestamp potentially affects the relative order in which readers observe events from multiple writers. Refer to DDSDestinationOrderQosModule 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.

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

The provided source_timestamp potentially affects the relative order in which readers observe events from multiple writers. Refer to DDSDestinationOrderQosModule 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.

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

See also: FooDataWriter.write_w_params

See also: FooDataWriter.write_w_params

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

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 DDSOwnershipQosModule). 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 procedure will fail with DDS.RETCODE_TIMEOUT.

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 procedure 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 procedure 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 procedure may fail with DDS.RETCODE_BAD_PARAMETER. \ifnot CPP_CPP2_LANGUAGE_ONLY This procedure 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 procedure will report the error DDS.RETCODE_BAD_PARAMETER.

self: <<in>> Cannot be NULL

Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_TIMEOUT or DDS.RETCODE_NOT_ENABLED

See also: FooDataWriter.register_instance
See also: FooDataWriter.unregister_instance_w_timestamp
See also: FooDataWriter.get_key_value
See also: Registration_liveliness_ownership

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

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 DDSOwnershipQosModule). 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 procedure will fail with DDS.RETCODE_TIMEOUT.

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 procedure 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 procedure 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 procedure may fail with DDS.RETCODE_BAD_PARAMETER. \ifnot CPP_CPP2_LANGUAGE_ONLY This procedure 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 procedure will report the error DDS.RETCODE_BAD_PARAMETER.

self: <<in>> Cannot be NULL

Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_TIMEOUT or DDS.RETCODE_NOT_ENABLED

See also: FooDataWriter.register_instance
See also: FooDataWriter.unregister_instance_w_timestamp
See also: FooDataWriter.get_key_value
See also: Registration_liveliness_ownership

The provided source_timestamp potentially affects the relative order in which readers observe events from multiple writers. Refer to DDSDestinationOrderQosModule 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.

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 procedure may fail with DDS.RETCODE_BAD_PARAMETER. \endif If Foo has a key, instance_data can be NULL only if handle is not DDS_HANDLE_NIL. Otherwise, this procedure 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 procedure may fail with DDS.RETCODE_BAD_PARAMETER. \ifnot CPP_CPP2_LANGUAGE_ONLY This procedure 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 procedure 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.

Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_TIMEOUT or DDS.RETCODE_NOT_ENABLED.

See also: FooDataWriter.register_instance
See also: FooDataWriter.unregister_instance
See also: FooDataWriter.get_key_value

The provided source_timestamp potentially affects the relative order in which readers observe events from multiple writers. Refer to DDSDestinationOrderQosModule 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.

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 procedure may fail with DDS.RETCODE_BAD_PARAMETER. \endif If Foo has a key, instance_data can be NULL only if handle is not DDS_HANDLE_NIL. Otherwise, this procedure 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 procedure may fail with DDS.RETCODE_BAD_PARAMETER. \ifnot CPP_CPP2_LANGUAGE_ONLY This procedure 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 procedure 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.

Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_TIMEOUT or DDS.RETCODE_NOT_ENABLED.

See also: FooDataWriter.register_instance
See also: FooDataWriter.unregister_instance
See also: FooDataWriter.get_key_value

See also: FooDataWriter.write_w_params
See also: FooDataWriter.dispose_w_params

See also: FooDataWriter.write_w_params
See also: FooDataWriter.dispose_w_params

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 DDSDestinationOrderQosModule 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 DDSReliabilityQosModule 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 DDSResourceLimitsQosModule to be exceeded.

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

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 DDSDestinationOrderQosModule 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 DDSReliabilityQosModule 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 DDSResourceLimitsQosModule to be exceeded.

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

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 DDSDestinationOrderQosModule 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 DDSReliabilityQosModule 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 DDSResourceLimitsQosModule to be exceeded.

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

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 DDSDestinationOrderQosModule 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 DDSReliabilityQosModule 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 DDSResourceLimitsQosModule to be exceeded.

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

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

self: <<in>> Cannot be NULL

instance_data: <<in>> The data to write. This procedure will fail with DDS.RETCODE_BAD_PARAMETER if instance_data is NULL. \endif

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 procedure may fail with DDS.RETCODE_BAD_PARAMETER. \ifnot CPP_CPP2_LANGUAGE_ONLY This procedure 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.

Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_TIMEOUT, DDS.RETCODE_OUT_OF_RESOURCES, or DDS.RETCODE_NOT_ENABLED.

See also: FooDataWriter.write
See also: DDS.DataReader
See also: DDSDestinationOrderQosModule

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

self: <<in>> Cannot be NULL

instance_data: <<in>> The data to write. This procedure will fail with DDS.RETCODE_BAD_PARAMETER if instance_data is NULL. \endif

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 procedure may fail with DDS.RETCODE_BAD_PARAMETER. \ifnot CPP_CPP2_LANGUAGE_ONLY This procedure 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.

Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_TIMEOUT, DDS.RETCODE_OUT_OF_RESOURCES, or DDS.RETCODE_NOT_ENABLED.

See also: FooDataWriter.write
See also: DDS.DataReader
See also: DDSDestinationOrderQosModule

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

self: <<in>> Cannot be NULL

instance_data: <<in>> The data to write. This procedure will fail with DDS.RETCODE_BAD_PARAMETER if instance_data is NULL. \endif

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 procedure may fail with DDS.RETCODE_BAD_PARAMETER. \ifnot CPP_CPP2_LANGUAGE_ONLY This procedure 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.

Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_TIMEOUT, DDS.RETCODE_OUT_OF_RESOURCES, or DDS.RETCODE_NOT_ENABLED.

See also: FooDataWriter.write
See also: DDS.DataReader
See also: DDSDestinationOrderQosModule

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

self: <<in>> Cannot be NULL

instance_data: <<in>> The data to write. This procedure will fail with DDS.RETCODE_BAD_PARAMETER if instance_data is NULL. \endif

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 procedure may fail with DDS.RETCODE_BAD_PARAMETER. \ifnot CPP_CPP2_LANGUAGE_ONLY This procedure 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.

Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_TIMEOUT, DDS.RETCODE_OUT_OF_RESOURCES, or DDS.RETCODE_NOT_ENABLED.

See also: FooDataWriter.write
See also: DDS.DataReader
See also: DDSDestinationOrderQosModule

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.

self: <<in>> Cannot be NULL

instance_data: <<in>> The data to write. \ifnot CPP_LANGUAGE_ONLY This procedure will fail with DDS.RETCODE_BAD_PARAMETER if instance_data is NULL. \endif

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 procedure will fail with DDS.RETCODE_BAD_PARAMETER if params is NULL.

Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_TIMEOUT, DDS.RETCODE_OUT_OF_RESOURCES or DDS.RETCODE_NOT_ENABLED.

See also: FooDataWriter.write
See also: DDS.DataReader

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.

self: <<in>> Cannot be NULL

instance_data: <<in>> The data to write. \ifnot CPP_LANGUAGE_ONLY This procedure will fail with DDS.RETCODE_BAD_PARAMETER if instance_data is NULL. \endif

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 procedure will fail with DDS.RETCODE_BAD_PARAMETER if params is NULL.

Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_TIMEOUT, DDS.RETCODE_OUT_OF_RESOURCES or DDS.RETCODE_NOT_ENABLED.

See also: FooDataWriter.write
See also: DDS.DataReader

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

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

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

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

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

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

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

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

RTI Connext 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 dispose() operation is for the instance as indicated by the handle.

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 freeing up some resources.

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 procedure 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 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 procedure fail with DDS.RETCODE_BAD_PARAMETER. This procedure will fail with DDS.RETCODE_BAD_PARAMETER if handle is NULL. If Foo has a key, instance_handle cannot be DDS_HANDLE_NIL if instance_data is NULL. Otherwise, this procedure will fail with DDS.RETCODE_BAD_PARAMETER.

Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_TIMEOUT, DDS.RETCODE_OUT_OF_RESOURCES or DDS.RETCODE_NOT_ENABLED.

See also: FooDataWriter.dispose_w_timestamp
See also: Registration_liveliness_ownership

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

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

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

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

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

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

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

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

RTI Connext 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 dispose() operation is for the instance as indicated by the handle.

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 freeing up some resources.

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 procedure 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 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 procedure fail with DDS.RETCODE_BAD_PARAMETER. This procedure will fail with DDS.RETCODE_BAD_PARAMETER if handle is NULL. If Foo has a key, instance_handle cannot be DDS_HANDLE_NIL if instance_data is NULL. Otherwise, this procedure will fail with DDS.RETCODE_BAD_PARAMETER.

Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_TIMEOUT, DDS.RETCODE_OUT_OF_RESOURCES or DDS.RETCODE_NOT_ENABLED.

See also: FooDataWriter.dispose_w_timestamp
See also: Registration_liveliness_ownership

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.

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. \endif If Foo has a key, instance_data can be NULL only if instance_handle is not DDS_HANDLE_NIL. Otherwise, this procedure will fail with DDS.RETCODE_BAD_PARAMETER.

@param 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 procedure may fail with DDS.RETCODE_BAD_PARAMETER. \ifnot CPP_CPP2_LANGUAGE_ONLY This procedure 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.

Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_TIMEOUT, DDS.RETCODE_OUT_OF_RESOURCES or DDS.RETCODE_NOT_ENABLED.

See also: FooDataWriter.dispose

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.

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. \endif If Foo has a key, instance_data can be NULL only if instance_handle is not DDS_HANDLE_NIL. Otherwise, this procedure will fail with DDS.RETCODE_BAD_PARAMETER.

@param 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 procedure may fail with DDS.RETCODE_BAD_PARAMETER. \ifnot CPP_CPP2_LANGUAGE_ONLY This procedure 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.

Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_TIMEOUT, DDS.RETCODE_OUT_OF_RESOURCES or DDS.RETCODE_NOT_ENABLED.

See also: FooDataWriter.dispose

See also: FooDataWriter.write_w_params

See also: FooDataWriter.write_w_params

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 procedure has no effect and exit 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.

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 procedure has no effect.

This procedure will fail with DDS.RETCODE_BAD_PARAMETER if key_holder is NULL. \endif

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 procedure will fail with DDS.RETCODE_BAD_PARAMETER. If Foo has a key and handle is DDS_HANDLE_NIL, this procedure will fail with DDS.RETCODE_BAD_PARAMETER. \ifnot CPP_CPP2_LANGUAGE_ONLY This procedure will fail with DDS.RETCODE_BAD_PARAMETER if handle is NULL.

Raises: One of the DDSReturnTypesModules_std_retcodes or DDS.RETCODE_NOT_ENABLED.

See also: FooDataReader.get_key_value

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 procedure has no effect and exit 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.

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 procedure has no effect.

This procedure will fail with DDS.RETCODE_BAD_PARAMETER if key_holder is NULL. \endif

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 procedure will fail with DDS.RETCODE_BAD_PARAMETER. If Foo has a key and handle is DDS_HANDLE_NIL, this procedure will fail with DDS.RETCODE_BAD_PARAMETER. \ifnot CPP_CPP2_LANGUAGE_ONLY This procedure will fail with DDS.RETCODE_BAD_PARAMETER if handle is NULL.

Raises: One of the DDSReturnTypesModules_std_retcodes or DDS.RETCODE_NOT_ENABLED.

See also: FooDataReader.get_key_value

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.

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 procedure has no effect and returns DDS_HANDLE_NIL

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.

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 procedure has no effect and returns DDS_HANDLE_NIL

This operation is supported while using RTIZeroCopyModule "Zero Copy transfer over shared memory" or 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.

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.

self: <<in>> Cannot be NULL

Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_OUT_OF_RESOURCES or DDS.RETCODE_PRECONDITION_NOT_MET.

See also: FooDataWriter.discard_loan

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

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

self: <<in>> Cannot be NULL

sample: <<in>> loaned sample to be discarded.

Raises: One of the DDSReturnTypesModules_std_retcodes or DDS.RETCODE_NOT_ENABLED.
See also: FooDataWriter.get_loan