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.

```
 
```
```
pragma Ada_05; 
```
```
 
```
```
limited with DDS.Subscriber; 
```
```
with DDS.TopicDescription; 
```
```
with DDS.DataReaderListener; 
```
```
with DDS.QueryCondition; 
```
```
with DDS.ReadCondition; 
```
```
with DDS.Domain_Entity; 
```
```
 
```
```
--  <dref>DataReader</dref> 
```
```
package DDS.DataReader is 
```
```
 
```

   type Ref is limited interface and DDS.Domain_Entity.RefTo API doc
To spec;

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

```
 
```
```
   --  Allows the application to: 
```

   --   (1) declare the data it wishes to receive (i.e. make a subscription) and

   --   (2) access the data received by the attached DDS.Subscriber.

```
   -- 
```

   --  A DDS.DataReader refers to exactly one DDS.TopicDescription

   --  (either a DDS.Topic, a DDS.ContentFilteredTopic or a DDS.MultiTopic)

   --  that identifies the data to be read.

   --  The subscription has a unique resulting type. The data-reader may give

   --  access to several instances of the resulting type,

   --  which can be distinguished from each other by their key.

```
   -- 
```

   --  DDS.DataReader is an abstract class.

   --  It must be specialised for each particular application data-type

   --  (see USER_DATA). The additional methods or functions that must be defined

   --  in the auto-generated class for a hypothetical application type Foo are

   --  specified in the generic type DDS.example.FooDataReader.

```
   -- 
```

   --  The following operations may be called even if the DDS.DataReader

   --  is not enabled. Other operations will fail with

   --  exception RETCODE_NOT_ENABLED if called on a disabled DDS.DataReader:

```
   -- 
```
```
   --  See also: 
```

   --      Operations Allowed in Listener Callbacks

```
 
```

   type Ref_Access_Access is access all Ref_AccessTo API doc
To spec;

   type Ref_Access_Array is array (NaturalTo API doc
To spec range <>) of aliased Ref_AccessTo API doc
To spec;

```
 
```
```
   procedure Initialize 
```

     (Self : in out Ref_AccessTo API doc
To spec) is null;

```
 
```
```
   procedure Finalize 
```

     (Self : in out Ref_AccessTo API doc
To spec) is null;

```
 
```
```
   procedure CopyTo API doc
To body 
```

     (Dst : in out Ref_AccessTo API doc
To spec;

      Src : in Ref_AccessTo API doc
To spec);

```
 
```
```
   function Create_Readcondition 
```

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

      Sample_States   : in DDS.SampleStateMaskTo API doc
To spec;

      View_States     : in DDS.ViewStateMaskTo API doc
To spec;

      Instance_States : in DDS.InstanceStateMaskTo API doc
To spec)

      return DDS.ReadCondition.Ref_AccessTo API doc
To spec is abstract;

   --  <dref>DataReader_create_readcondition</dref>

```
   --  <internal> 
```

   --  The returned DDS.ReadCondition will be

   --  attached and belong to the DDS.DataReader.

```
   --  </internal> 
```
```
 
```
```
   function Create_Querycondition 
```

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

      Sample_States    : in DDS.SampleStateMaskTo API doc
To spec;

      View_States      : in DDS.ViewStateMaskTo API doc
To spec;

      Instance_States  : in DDS.InstanceStateMaskTo API doc
To spec;

      Query_Expression : in DDS.StringTo API doc
To spec;

      Query_Parameters : in DDS.String_Seq.SequenceTo API doc
To spec)

      return DDS.QueryCondition.Ref_AccessTo API doc
To spec is abstract;

   --  <dref>DataReader_create_querycondition</dref>

```
   --  <internal> 
```

   --  Not supported (optional>> Creates a DDS.QueryCondition.

   --  The returned DDS.QueryCondition will be attached

   --  and belong to the DDS.DataReader.

   --  Queries and Filters Syntax describes the syntax of

   --  query_expression and query_parameter

```
   --  </internal> 
```
```
 
```
```
   procedure Delete_Readcondition 
```

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

      A_Condition : access DDS.ReadCondition.RefTo API doc
To spec'Class) is abstract;

   --  <dref>DataReader_delete_readcondition</dref>

```
 
```

   procedure  Delete_Contained_Entities

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

   --  <dref>DataReader_delete_contained_entities</dref>

```
   --  <internal> 
```

   --  Deletes all the entities that were created by means of the "create"

   --  operations on the dds.DataReader.

   --  Deletes all contained dds.ReadCondition and dds.QueryCondition objects.

   --  The operation will fail with RETCODE_PRECONDITION_NOT_MET if the any of

   --  the contained entities is in a state where it cannot be deleted.

   --  Once dds.DataReader.delete_contained_entities completes successfully,

   --  the application may delete the dds.DataReader, knowing that it has no

   --  contained dds.ReadCondition and dds.QueryCondition objects.

```
   --  </internal> 
```
```
 
```
```
   procedure Set_Qos 
```

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

      Qos  : in DDS.DataReaderQoSTo API doc
To spec) is abstract;

```
   --  <dref>DataReader_set_qos</dref> 
```
```
 
```
```
   procedure Set_Qos_With_Profile 
```

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

      library_name  : in StringTo API doc
To spec;

      profile_name  : in StringTo API doc
To spec) is abstract;

```
   procedure Set_Qos_With_Profile 
```

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

      library_name  : in Standard.StringTo API doc
To spec;

      profile_name  : in Standard.StringTo API doc
To spec) is abstract;

   --  <dref>DataReader_set_qos_with_profile</dref>

```
   --  <internal> 
```

   --  This operation modifies the QoS of the DDS.DataReader.

```
   --  The DataReaderQos.user_data, 
```
```
   --      DataReaderQos.deadline, 
```

   --      DataReaderQos.latency_budget,

   --      DataReaderQos.time_based_filter,

   --      DataReaderQos.reader_data_lifecycle

```
   --  can be changed. 
```

   --  The other policies are immutable.

```
   --  </internal> 
```
```
 
```
```
 
```
```
   procedure Get_Qos 
```

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

      Qos  : in out DDS.DataReaderQoSTo API doc
To spec) is abstract;

```
   --  <dref>DataReader_get_qos</dref> 
```
```
   --  <internal> 
```
```
   --  Gets the reader QoS. 
```

   --  This method may potentially allocate memory depending on the sequences

```
   --  contained in some QoS policies 
```
```
   --  </internal> 
```
```
 
```
```
 
```
```
   procedure Set_Listener 
```

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

      A_Listener : in DDS.DataReaderListener.Ref_AccessTo API doc
To spec;

      Mask       : in DDS.StatusMaskTo API doc
To spec) is abstract;

   --  <dref>DataReader_set_listener</dref>

```
   --  <internal> 
```
```
   --  Sets the reader listener. 
```
```
   --  </internal> 
```
```
 
```
```
 
```
```
   function Get_Listener 
```

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

      return DDS.DataReaderListener.Ref_AccessTo API doc
To spec is abstract;

   --  <dref>DataReader_get_listener</dref>

```
   --  <internal> 
```
```
   --  Get the reader listener 
```
```
   --  </internal> 
```
```
 
```
```
   procedure Call_ListnerT 
```

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

      A_Listener : in DDS.DataReaderListener.Ref_AccessTo API doc
To spec;

      Mask       : in DDS.StatusMaskTo API doc
To spec) is abstract;

```
   --  <internal> 
```
```
   --  Calls the reader listener. 
```
```
   --  </internal> 
```
```
 
```
```
   function Get_Topicdescription 
```

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

      return DDS.TopicDescription.Ref_AccessTo API doc
To spec is abstract;

   --  <dref>DataReader_get_topicdescription</dref>

```
   --  <internal> 
```

   --  Returns the dds.TopicDescription associated with the dds.DataReader.

```
   --  </internal> 
```
```
 
```
```
   function Get_Subscriber 
```

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

      return access DDS.Subscriber.RefTo API doc
To spec'Class is abstract;

   --  <dref>DataReader_get_subscriber</dref>

```
   --  <internal> 
```

   --  Returns the dds.Subscriber to which the dds.DataReader belongs.

```
   --  </internal> 
```
```
 
```
```
 
```

   procedure Get_Sample_Rejected_Status

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

      Status : in out DDS.SampleRejectedStatusTo API doc
To spec) is abstract;

   --  <dref>DataReader_get_sample_rejected_status</dref>

```
   --  <internal> 
```

   --  Return the StatusKind.SAMPLE_REJECTED_STATUS communication status.

```
   --  </internal> 
```
```
 
```

   procedure Get_Liveliness_Changed_Status

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

      Status : in out DDS.LivelinessChangedStatusTo API doc
To spec) is abstract;

   --  <dref>DataReader_get_liveliness_changed_status</dref>

```
   --  <internal> 
```

   --  Returns the StatusKind.LIVELINESS_CHANGED_STATUS communication status.

```
   --  </internal> 
```
```
 
```

   procedure Get_Requested_Deadline_Missed_Status

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

      Status : in out DDS.RequestedDeadlineMissedStatusTo API doc
To spec) is abstract;

   --  <dref>DataReader_get_requested_deadline_missed_status</dref>

```
   --  <internal> 
```

   --  Returns the StatusKind.REQUESTED_DEADLINE_MISSED_STATUS

```
   --  communication status. 
```
```
   --  </internal> 
```
```
 
```

   procedure Get_Requested_Incompatible_Qos_Status

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

      Status : in out DDS.RequestedIncompatibleQosStatusTo API doc
To spec) is abstract;

   --  <dref>DataReader_get_requested_incompatible_qos_status</dref>

```
   --  <internal> 
```

   --  Returns the StatusKind.REQUESTED_INCOMPATIBLE_QOS_STATUS

```
   --  communication status 
```
```
   --  </internal> 
```
```
 
```

   procedure Get_Subscription_Matched_Status

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

      Status : in out DDS.SubscriptionMatchedStatusTo API doc
To spec) is abstract;

   --  <dref>DataReader_get_subscription_matched_status</dref>

```
   --  <internal> 
```

   --  Returns the StatusKind.SUBSCRIPTION_MATCHED_STATUS communication status.

```
   --  </internal> 
```
```
 
```
```
   procedure Get_Sample_Lost_Status 
```

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

      Status : in out DDS.SampleLostStatusTo API doc
To spec) is abstract;

   --  <dref>DataReader_get_sample_lost_status</dref>

```
   --  <internal> 
```

   --  Returns the StatusKind.SAMPLE_LOST_STATUS_STATUS communication status

```
   --  </internal> 
```
```
 
```

   procedure Get_Datareader_Cache_Status

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

      Status : in out DDS.DataReaderCacheStatusTo API doc
To spec) is abstract;

   --  <dref>DataReader_get_datareader_cache_status</dref>

```
   --  <internal> 
```

   --  Returns the StatusKind.DATA_READER_CACHE_STATUS communication status

```
   --  </internal> 
```
```
 
```

   procedure Get_Datareader_Protocol_Status

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

      Status : in out DDS.DataReaderProtocolStatusTo API doc
To spec) is abstract;

   --  <dref>DataReader_get_datareader_protocol_status</dref>

```
   --  <internal> 
```

   --  Returns the StatusKind.DATA_READER_PROTOCOL_STATUS communication status

```
   --  </internal> 
```
```
 
```

   procedure Get_Matched_Publication_Datareader_Protocol_Status

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

      Status : in out DDS.DataReaderProtocolStatusTo API doc
To spec;

      Publication_Handle : not null access DDS.InstanceHandle_TTo API doc
To spec) is abstract;

   --  <dref>DataReader_get_matched_publication_datareader_protocol_status</dref>

```
   --  <internal> 
```

   --  Returns the StatusKind.DATA_READER_PROTOCOL_STATUS communication status

   --  for this reader, per matched publication identified by the

```
   --  Publication_Handle. 
```
```
   --  </internal> 
```
```
 
```
```
   procedure Wait_For_Historical_Data 
```

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

      Max_Wait : in DDS.Duration_TTo API doc
To spec) is abstract;

   --  <dref>DataReader_wait_for_historical_data</dref>

```
   --  <internal> 
```

   --  Waits until all "historical" data is received for dds.DataReader entities

   --  that have a non-VOLATILE PERSISTENCE Qos kind.

   --  This operation is intended only for dds.DataReader entities that have a

   --  non-VOLATILE PERSISTENCE QoS kind.

   --  As soon as an application enables a non-VOLATILE dds.DataReader, it will

   --  start receiving both "historical" data, i.e. the data that was written

   --  prior to the time the dds.DataReader joined the domain, as well as any

   --  new data written by the dds.DataWriter entities.

   --  There are situations where the application logic may require the

   --  application to wait until all "historical" data is received.

   --  This is the purpose of the dds.DataReader.wait_for_historical_data operations.

   --  The operation dds.DataReader.wait_for_historical_data blocks the calling

   --  thread until either all "historical" data is received, or else duration

   --  specified by the max_wait parameter clapses, whichever happens first.

   --  A successful completion indicates that all the "historical" data was

   --  "received"; timing out indicates that max_wait elapsed before all the

```
   --  data was received 
```
```
   --  </internal> 
```
```
 
```
```
 
```
```
   function Get_Matched_Publications 
```

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

      return DDS.InstanceHandle_Seq.SequenceTo API doc
To spec is abstract;

   --  <dref>DataReader_get_matched_publications</dref>

```
   --  <internal> 
```

   --  Retrieve the list of publications currently "associated" with this

```
   --  DDS.DataReader. 
```

   --  Matching publications are those in the same domain that have a matching

   --  DDS.Topic, compatible QoS common partition that the DDS.DomainParticipant

   --  has not indicated should be "ignored" by means of the

   --  DDS.DomainParticipant.ignore_publication operation.

   --  The handles returned in the publication_handles' list are the ones that

   --  are used by the DDS implementation to locally identify the corresponding

```
   --  matched DDSDataWriter entities. 
```

   --  These handles match the ones that appear in the instance_handle field

   --  of the DDS.SampleInfo when reading the

   --  PublicationBuiltinTopicDataTypeSupport.PUBLICATION_TOPIC_NAME builtin topic

   --  The sequence will be grown if the sequence has ownership and the system

   --  has the corresponding resources. Use a sequence without ownership to

   --  avoid dynamic memory allocation. If the sequence is too small to

   --  store all the matches and the system can not resize the sequence,

   --  this method will fail with RETCODE_OUT_OF_RESOURCES.

   --  The maximum number of matches possible is configured with

   --  DDS.DomainParticipantResourceLimitsQosPolicy.

   --  You can use a zero-maximum sequence without ownership to quickly check

   --  whether there are any matches without allocating any memory.

```
   --  </internal> 
```
```
 
```

   function Get_Matched_Publication_Data

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

      Publication_Handle : not null access DDS.InstanceHandle_TTo API doc
To spec)

      return DDS.PublicationBuiltinTopicDataTo API doc
To spec is abstract;

   --  <dref>DataReader_get_matched_publication_data</dref>

```
   --  <internal> 
```

   --  This operation retrieves the information on a publication that is

   --  currently "associated" with the dds.DataReader.

   --  Publication with a matching dds.Topic, compatible QoS and common

   --  partition that the application has not indicated should be "ignored"

   --  by means of the dds.DomainParticipant.ignore_publication operation.

   --  The publication_handle must correspond to a publication currently

   --  associated with the dds.DataReader. Otherwise, the operation will fail

```
   --   with RETCODE_BAD_PARAMETER. 
```

   --  use the operation dds.DataReader.get_matched_publications to find the

   --  publications that are currently matched with the DDS.DataReader.

```
   --  </internal> 
```
```
 
```
```
end DDS.DataReader; 
```

RTI Connext Ada API