File:

--  (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 TreatsTo API doc
To spec; 
```

package DDS.Typed_DataWriter_Generic is

```
 
```

   type Ref is new Standard.DDS.DataWriter_Impl.RefTo API doc
To spec with null record;

   type Ref_Access is access all RefTo API doc
To spec'Class;

```
 
```

   function Register_InstanceTo API doc
To body

     (Self          : not null access RefTo API doc
To spec;

      Instance_Data : not null Data_Type_AccessTo API doc
To spec)

      return Standard.DDS.InstanceHandle_TTo API doc
To spec;

   --  <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_TimestampTo API doc
To body

     (Self             : not null access RefTo API doc
To spec;

      Instance_Data    : not null Data_Type_AccessTo API doc
To spec;

      Source_TimestampTo API doc
To body : in Standard.DDS.Time_TTo API doc
To spec)

      return Standard.DDS.InstanceHandle_TTo API doc
To spec;

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

   procedure Unregister_InstanceTo API doc
To body

     (Self          : not null access RefTo API doc
To spec;

      Instance_Data : not null Data_Type_AccessTo API doc
To spec;

      HandleTo API doc
To body        : in Standard.DDS.InstanceHandle_TTo API doc
To spec);

   --  <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_TimestampTo API doc
To body

     (Self              : not null access RefTo API doc
To spec;

      Instance_Data    : not null Data_Type_AccessTo API doc
To spec;

      HandleTo API doc
To body           : in Standard.DDS.InstanceHandle_TTo API doc
To spec;

      Source_TimestampTo API doc
To body : in Standard.DDS.Time_TTo API doc
To spec);

   --  <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 WriteTo API doc
To body 
```

     (Self           : not null access RefTo API doc
To spec;

      Instance_Data : not null Data_Type_AccessTo API doc
To spec;

      Handle        : in Standard.DDS.InstanceHandle_T_AccessTo API doc
To spec);

   --  <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_TimestampTo API doc
To body

     (Self           : not null access RefTo API doc
To spec;

      Instance_Data    : not null Data_Type_AccessTo API doc
To spec;

      Handle           : in Standard.DDS.InstanceHandle_T_AccessTo API doc
To spec;

      Source_TimestampTo API doc
To body : in Standard.DDS.Time_TTo API doc
To spec);

   --  <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 DisposeTo API doc
To body 
```

     (Self            : not null access RefTo API doc
To spec;

      Instance_Data   : not null Data_Type_AccessTo API doc
To spec;

      Instance_HandleTo API doc
To body : in Standard.DDS.InstanceHandle_TTo API doc
To spec);

   --  <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_TimestampTo API doc
To body

     (Self             : not null access RefTo API doc
To spec;

      Instance_Data    : not null Data_Type_AccessTo API doc
To spec;

      Instance_HandleTo API doc
To body  : in Standard.DDS.InstanceHandle_TTo API doc
To spec;

      Source_TimestampTo API doc
To body : in Standard.DDS.Time_TTo API doc
To spec);

   --  <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 Get_Key_ValueTo API doc
To body

     (Self       : not null access RefTo API doc
To spec;

      Key_Holder : not null Data_Type_AccessTo API doc
To spec;

      HandleTo API doc
To body     : in Standard.DDS.InstanceHandle_TTo API doc
To spec);

   --  <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_InstanceTo API doc
To body

     (Self        : not null access RefTo API doc
To spec;

      Key_Holder : not null Data_Type_AccessTo API doc
To spec) return Standard.DDS.InstanceHandle_TTo API doc
To spec;

   --  <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 NarrowTo API doc
To body 
```

     (Self        : access DDS.DataWriter.RefTo API doc
To spec'Class) return not null access RefTo API doc
To spec;

```
 
```

   --  =========================================================================

```
   -- 
```

   --  Internal Routines not to be used by the application

```
   -- 
```

   --  =========================================================================

```
 
```

   function CreateTypedITo API doc
To body return Standard.DDS.DataWriter.Ref_AccessTo API doc
To spec;

```
 
```

   procedure DestroyTypedITo API doc
To body

     (Writer : in out Standard.DDS.DataWriter.Ref_AccessTo API doc
To spec);

```
 
```
```
end DDS.Typed_DataWriter_Generic; 
```

RTI Connext Ada API