-- (c) Copyright, Real-Time Innovations, $Date:: 2012-02-16 #$
-- All rights reserved.
--
-- No duplications, whole or partial, manual or electronic, may be made
-- without express written permission. Any such copies, or
-- revisions thereof, must display this notice unaltered.
-- This code contains trade secrets of Real-Time Innovations, Inc.
with DDS.DataWriter;
with DDS.DataWriter_Impl;
with DDS.Treats_Generic;
generic
with package Treats is new DDS.Treats_Generic (<>);
use Treats;
package DDS.Typed_DataWriter_Generic is
pragma Suppress (Elaboration_Check);
type Ref is new Standard.DDS.DataWriter_Impl.Ref with null record;
type Ref_Access is access all Ref'Class;
function Register_Instance
(Self : not null access Ref;
Instance_Data : Data_Type)
return Standard.DDS.InstanceHandle_T;
-- <dref>FooDataWriter_register_instance</dref>
function Register_Instance
(Self : not null access Ref;
Instance_Data : not null Data_Type_Access)
return Standard.DDS.InstanceHandle_T;
-- <dref>FooDataWriter_register_instance</dref>
-- <internal>
-- Informs Data Distribution Service 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 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 Data Distribution Service 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 HANDLE_NIL as the InstanceHandle_t paramater to the write or dispose
-- operation and Data Distribution Service will auto-register the instance.
-- For best performance, the operation should be invoked prior to calling any
-- operation that modifies the instance, such as write, write_w_timestamp,
-- dispose and dispose_w_timestamp and the handle used in conjunction with
-- the data for those calls.
-- When this operation is used, Data Distribution Service will automatically supply
-- the value of the source_timestamp that is used.
-- This operation may fail and return HANDLE_NIL if 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 DataWriter has been enabled.
-- Otherwise, HANDLE_NIL will be returned.
-- </internal>
function Register_Instance_W_Timestamp
(Self : not null access Ref;
Instance_Data : Data_Type;
Source_Timestamp : in Standard.DDS.Time_T)
return Standard.DDS.InstanceHandle_T;
-- <dref>FooDataWriter_register_instance_w_timestamp</dref>
function Register_Instance_W_Timestamp
(Self : not null access Ref;
Instance_Data : Data_Type_Access;
Source_Timestamp : in Standard.DDS.Time_T)
return Standard.DDS.InstanceHandle_T;
-- <dref>FooDataWriter_register_instance_w_timestamp</dref>
-- <internal>
-- Performs the same functions as register_instance except that the application
-- provides the value for the source_timestamp.
-- The provided source_timestamp potentially affects the relative order in which
-- readers observe events from multiple writers. Refer to DESTINATION_ORDER QoS policy for details.
-- This operation may fail and return DDS_HANDLE_NIL if ResourceLimitsQosPolicy::max_instances
-- limit has been exceeded.
-- This operation can only be called after DataWriter has been enabled.
-- Otherwise, HANDLE_NIL will be returned.
-- </internal>
function Register_Instance_W_Params
(Self : not null access Ref;
Instance_Data : not null Data_Type_Access;
Params : not null access DDS.WriteParams_T)
return Standard.DDS.InstanceHandle_T;
-- <dref>FooDataWriter_register_instance_w_params</dref>
function Register_Instance_W_Params
(Self : not null access Ref;
Instance_Data : Data_Type;
Params : not null access DDS.WriteParams_T)
return Standard.DDS.InstanceHandle_T;
-- <dref>FooDataWriter_register_instance_w_params</dref>
-- <internal>
-- Performs the same functions as register_instance except that ...
-- readers observe events from multiple writers. Refer to DESTINATION_ORDER QoS policy for details.
-- This operation may fail and return DDS_HANDLE_NIL if ResourceLimitsQosPolicy::max_instances
-- limit has been exceeded.
-- This operation can only be called after DataWriter has been enabled.
-- Otherwise, HANDLE_NIL will be returned.
-- </internal>
procedure Unregister_Instance
(Self : not null access Ref;
Instance_Data : Data_Type;
Handle : in Standard.DDS.InstanceHandle_T);
-- <dref>FooDataWriter_unregister_instance</dref>
procedure Unregister_Instance
(Self : not null access Ref;
Instance_Data : not null Data_Type_Access;
Handle : in Standard.DDS.InstanceHandle_T);
-- <dref>FooDataWriter_unregister_instance</dref>
-- <internal>
-- Reverses the action of 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 register_instance. Otherwise, this operation may
-- fail with exception 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, DDS will automatically supply
-- the value of the source_timestamp that is used.
-- This operation informs DDS that the DataWriter is no longer
-- going to provide any information about the instance. This operation also indicates
-- that DDS can locally remove all information regarding that instance.
-- The application should not attempt to use the handle previously allocated to
-- that instance after calling unregister_instance().
-- The special value 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 HANDLE_NIL, then it must correspond to an instance
-- that has been registered. If there is no correspondence, the operation will fail with
-- exception BAD_PARAMETER.
-- DDS will not detect the error when the handle is any value other than 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). DDS will treat as if
-- the unregister_instance() operation is for the instance as indicated by the handle.
-- If after a unregister_instance, the application wants to modify (write or dispose)
-- an instance, it has to register it again, or else use the special handle value HANDLE_NIL.
-- This operation does not indicate that the instance is deleted
-- (that is the purpose of dispose). The operation unregister_instance just indicates
-- that the DataWriter no longer has anything to say about the instance. DataReader
-- entities that are reading the instance may receive a sample with
-- NOT_ALIVE_NO_WRITERS_INSTANCE_STATE for the instance, unless there are other
-- DataWriter objects writing that same instance.
-- This operation can affect the ownership of the data instance (see OWNERSHIP).
-- If the DataWriter was the exclusive owner of the instance, then calling
-- unregister_instance() will relinquish that ownership.
-- If ReliabilityQosPolicy::kind is set to 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 ReliabilityQosPolicy::max_blocking_time; if this writer is
-- still unable to unregister after that period, this function will fail with exception TIMEOUT.
-- </internal>
procedure Unregister_Instance_W_Timestamp
(Self : not null access Ref;
Instance_Data : Data_Type;
Handle : in Standard.DDS.InstanceHandle_T;
Source_Timestamp : in Standard.DDS.Time_T);
-- <dref>FooDataWriter_unregister_instance_w_timestamp</dref>
procedure Unregister_Instance_W_Timestamp
(Self : not null access Ref;
Instance_Data : Data_Type_Access;
Handle : in Standard.DDS.InstanceHandle_T;
Source_Timestamp : in Standard.DDS.Time_T);
-- <dref>FooDataWriter_unregister_instance_w_timestamp</dref>
-- <internal>
-- Performs the same function as 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 unregister_instance operation.
-- This operation may block and may time out (exception RETCODE_TIMEOUT) under
-- the same circumtances described for the unregister_instance operation.
-- </internal>
procedure Unregister_Instance_W_Params
(Self : not null access Ref;
Instance_Data : Data_Type;
Params : access DDS.WriteParams_T);
-- <dref>FooDataWriter_unregister_instance_w_params</dref>
procedure Unregister_Instance_W_Params
(Self : not null access Ref;
Instance_Data : Data_Type_Access;
Params : access DDS.WriteParams_T);
-- <dref>FooDataWriter_unregister_instance_w_params</dref>
procedure Write
(Self : not null access Ref;
Instance_Data : Data_Type;
Handle : in Standard.DDS.InstanceHandle_T_Access);
-- <dref>FooDataWriter_write</dref>
procedure Write
(Self : not null access Ref;
Instance_Data : Data_Type;
Handle : in Standard.DDS.InstanceHandle_T);
-- <dref>FooDataWriter_write</dref>
procedure Write
(Self : not null access Ref;
Instance_Data : not null Data_Type_Access;
Handle : in Standard.DDS.InstanceHandle_T_Access);
-- <dref>FooDataWriter_write</dref>
procedure Write
(Self : not null access Ref;
Instance_Data : not null Data_Type_Access;
Handle : in Standard.DDS.InstanceHandle_T);
-- <dref>FooDataWriter_write</dref>
-- <internal>
-- Modifies the value of a data instance.
-- When this operation is used, DDS will automatically supply the value of the
-- source_timestamp that is made available to DataReader objects by means of the
-- source_timestamp attribute inside the SampleInfo.
-- (Refer to SampleInfo and DESTINATION_ORDER QoS policy for details).
-- As a side effect, this operation asserts liveliness on the DataWriter itself,
-- the Publisher and the DomainParticipant.
-- Note that the special value 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 HANDLE_NIL, then it must correspond to an instance
-- that has been registered. If there is no correspondence, the operation will fail
-- with exception BAD_PARAMETER.
-- DDS will not detect the error when the handle is any value other than 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).
-- DDS 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 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 HistoryQosPolicyKind is KEEP_LAST_HISTORY_QOS:
-- * If (ResourceLimitsQosPolicy::max_samples <
-- ResourceLimitsQosPolicy::max_instances * HistoryQosPolicy::depth),
-- then in the situation where the max_samples resource limit is exhausted,
-- DDS 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 (ResourceLimitsQosPolicy::max_samples < ResourceLimitsQosPolicy::max_instances),
-- then the DataWriter may block regardless of the HistoryQosPolicy::depth.
-- This operation may also block when using BEST_EFFORT_RELIABILITY_QOS and
-- ASYNCHRONOUS_PUBLISH_MODE_QOS. In this case, the 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 HistoryQosPolicy.
-- If the asynchronous thread does not send samples fast enough
-- (e.g., when using a slow 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 DataWriter is able to store the modification without exceeding the limits,
-- the operation will time out (exception TIMEOUT).
-- If there are no instance resources left, this operation may fail with exception
-- OUT_OF_RESOURCES. Calling DataWriter.unregister_instance may help
-- freeing up some resources.
-- </internal>
procedure Write_W_Timestamp
(Self : not null access Ref;
Instance_Data : Data_Type;
Handle : not null Standard.DDS.InstanceHandle_T_Access;
Source_Timestamp : in Standard.DDS.Time_T);
-- <dref>FooDataWriter_write_w_timestamp</dref>
procedure Write_W_Timestamp
(Self : not null access Ref;
Instance_Data : Data_Type_Access;
Handle : not null Standard.DDS.InstanceHandle_T_Access;
Source_Timestamp : in Standard.DDS.Time_T);
-- <dref>FooDataWriter_write_w_timestamp</dref>
procedure Write_W_Timestamp
(Self : not null access Ref;
Instance_Data : Data_Type;
Handle : in Standard.DDS.InstanceHandle_T;
Source_Timestamp : in Standard.DDS.Time_T);
-- <dref>FooDataWriter_write_w_timestamp</dref>
procedure Write_W_Timestamp
(Self : not null access Ref;
Instance_Data : Data_Type_Access;
Handle : in Standard.DDS.InstanceHandle_T;
Source_Timestamp : in Standard.DDS.Time_T);
-- <dref>FooDataWriter_write_w_timestamp</dref>
-- <internal>
-- Performs the same function as write except that it also provides the value
-- for the source_timestamp.
-- Explicitly provides the timestamp that will be available to the DataReader objects
-- by means of the source_timestamp attribute inside the SampleInfo.
-- (Refer to 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 write operation.
-- This operation may block and time out (exception TIMEOUT)
-- under the same circumtances described for write.
-- If there are no instance resources left, this operation may fail with
-- exception OUT_OF_RESOURCES. Calling unregister_instance may help free up some resources.
-- This operation may fail with exception BAD_PARAMETER under the same circumstances
-- described for the write operation.
-- </internal>
procedure Write_W_Params (Self : not null access Ref;
Instance_Data : Data_Type;
Params : in out DDS.WriteParams_T);
-- <dref>FooDataWriter_write_w_params</dref>
procedure Write_W_Params (Self : not null access Ref;
Instance_Data : not null Data_Type_Access;
Params : in out DDS.WriteParams_T);
-- <dref>FooDataWriter_write_w_params</dref>
-- <internal>
-- Performs the same function as write and 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. Allows provision of the sample identity, instance handle, source timestamp,
-- The constraints on the values of the handle parameter and the corresponding error
-- behavior are the same specified for the 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 (DDS_RETCODE_TIMEOUT) under
-- the same circumtances described for write.
--
-- If there are no instance resources left, this operation may fail with DDS_RETCODE_OUT_OF_RESOURCES.
-- Calling unregister_instance_w_params may help free up some resources.
--
-- The handle is either returned by a previous call to DataWriter_register_instance,
-- or else the special value DDS_HANDLE_NIL. If Foo has a key and handle is not DDS_HANDLE_NIL,
-- handle must represent a registered instance of type Foo. Otherwise,
-- this function may fail with DDS_RETCODE_BAD_PARAMETER.
-- 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
-- DDS.DataReader objects by means of the source_timestamp attribute
-- inside the DDS.SampleInfo.
-- </internal>
procedure Dispose
(Self : not null access Ref;
Instance_Data : Data_Type;
Instance_Handle : in Standard.DDS.InstanceHandle_T);
-- <dref>FooDataWriter_dispose</dref>
procedure Dispose
(Self : not null access Ref;
Instance_Data : not null Data_Type_Access;
Instance_Handle : in Standard.DDS.InstanceHandle_T);
-- <dref>FooDataWriter_dispose</dref>
-- <internal>
-- 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 DataReader
-- objects that already knew that instance. 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, DDS will automatically
-- supply the value of the source_timestamp that is made available to DataReader
-- objects by means of the source_timestamp attribute inside the SampleInfo.
-- The constraints on the values of the handle parameter and the corresponding
-- error behavior are the same specified for the DataWriter.unregister_instance operation.
-- The special value 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 HANDLE_NIL, then it must correspond to an
-- instance that has been registered. If there is no correspondence, the operation
-- will fail with exception BAD_PARAMETER.
-- DDS will not detect the error when the handle is any
-- value other than 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).
-- DDS will treat as if the dispose() operation is for the instance as indicated by the handle.
-- This operation may block and time out (exception TIMEOUT) under the same
-- circumtances described for write().
-- If there are no instance resources left, this operation may fail with exception OUT_OF_RESOURCES.
-- Calling unregister_instance may help freeing up some resources.
-- </internal>
procedure Dispose_W_Timestamp
(Self : not null access Ref;
Instance_Data : Data_Type;
Instance_Handle : in Standard.DDS.InstanceHandle_T;
Source_Timestamp : in Standard.DDS.Time_T);
-- <dref>FooDataWriter_dispose_w_timestamp</dref>
procedure Dispose_W_Timestamp
(Self : not null access Ref;
Instance_Data : not null Data_Type_Access;
Instance_Handle : in Standard.DDS.InstanceHandle_T;
Source_Timestamp : in Standard.DDS.Time_T);
-- <dref>FooDataWriter_dispose_w_timestamp</dref>
-- <internal>
-- Performs the same functions as dispose except that the application provides
-- the value for the source_timestamp that is made available to DataReader objects
-- by means of the source_timestamp attribute inside the SampleInfo.
-- The constraints on the values of the handle parameter and the corresponding
-- error behavior are the same specified for the dispose operation.
-- This operation may block and time out (exception TIMEOUT) under the same
-- circumtances described for write.
-- If there are no instance resources left, this operation may fail
-- with exception OUT_OF_RESOURCES.
-- Calling unregister_instance may help freeing up some resources.
-- </internal>
procedure Dispose_W_Params
(Self : not null access Ref;
Instance_Data : Data_Type;
Params : in DDS.WriteParams_T);
-- <dref>FooDataWriter_dispose_w_params</dref>
procedure Dispose_W_Params
(Self : not null access Ref;
Instance_Data : not null Data_Type_Access;
Params : in DDS.WriteParams_T);
-- <dref>FooDataWriter_dispose_w_params</dref>
procedure Get_Key_Value
(Self : not null access Ref;
Key_Holder : out Data_Type;
Handle : in Standard.DDS.InstanceHandle_T);
-- <dref>FooDataWriter_get_key_value</dref>
-- <internal>
-- Retrieve the instance key that corresponds to an instance handle.
-- Useful for keyed data types.
-- The operation will only fill the fields that form the key inside the key_holder instance.
-- If the data has no key, this function has no effect and exit with no error.
-- For keyed data types, this operation may fail with exception BAD_PARAMETER
-- if the handle does not correspond to an existing data-object known to the DataWriter.
-- </internal>
procedure Get_Key_Value
(Self : not null access Ref;
Key_Holder : not null Data_Type_Access;
Handle : in Standard.DDS.InstanceHandle_T);
-- <dref>FooDataWriter_get_key_value</dref>
-- <internal>
-- Retrieve the instance key that corresponds to an instance handle.
-- Useful for keyed data types.
-- The operation will only fill the fields that form the key inside the key_holder instance.
-- If the data has no key, this function has no effect and exit with no error.
-- For keyed data types, this operation may fail with exception BAD_PARAMETER
-- if the handle does not correspond to an existing data-object known to the DataWriter.
-- </internal>
function Lookup_Instance
(Self : not null access Ref;
Key_Holder : Data_Type) return Standard.DDS.InstanceHandle_T;
-- <dref>FooDataWriter_lookup_instance</dref>
-- <internal>
-- 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
-- DDS is unable to provide an instance handle, DDS will return the special value HANDLE_NIL.
-- </internal>
function Lookup_Instance
(Self : not null access Ref;
Key_Holder : not null Data_Type_Access) return Standard.DDS.InstanceHandle_T;
-- <dref>FooDataWriter_lookup_instance</dref>
-- <internal>
-- 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
-- DDS is unable to provide an instance handle, DDS will return the special value HANDLE_NIL.
-- </internal>
function Get_Loan (Self : not null access Ref) return Data_Type_Access;
-- <dref>FooDataWriter_get_loan</dref>
-- <internal>
-- When using SHMEM_REF transfer mode, this operation will return a sample
-- access loaned from the DataWriter. By using this loaned sample instead
-- of creating new samples through the TypeSupport package, the writer does
-- not need to make an additional copy to its output buffers before sending
-- it to matching data readers.
-- The loan will be returned during the write operation. If a sample has
-- been obtained with this operation but will finally not be written, the
-- loaned sample must be returned to the DataWriter using Discard_Loan.
-- </internal>
procedure Discard_Loan (Self : not null access Ref; Sample : not null Data_Type_Access);
-- <dref>FooDataWriter_discard_loan</dref>
-- <internal>
-- Discard a loaned sample obtained previously with Get_Loan. This
-- operation should only be used if the sample is not going to be written
-- with a write operation. Otherwise, the write operation itself will
-- return the loan.
-- </internal>
function As_DataWriter (Self : Ref_Access) return Standard.DDS.DataWriter.Ref_Access is
(Standard.DDS.DataWriter.Ref_Access (Self));
function Narrow
(Self : access DDS.DataWriter.Ref'Class) return not null access Ref is
(if Self = null then null else Ref (Self.all)'Access);
function CreateTypedI return Standard.DDS.DataWriter.Ref_Access;
procedure DestroyTypedI
(Writer : in out Standard.DDS.DataWriter.Ref_Access);
end DDS.Typed_DataWriter_Generic;