1. pragma Ada_2012; 
  2. --  (c) Copyright, Real-Time Innovations, $Date:: 2012-02-16 #$ 
  3. --  All rights reserved. 
  4. -- 
  5. --  No duplications, whole or partial, manual or electronic, may be made 
  6. --  without express written permission.  Any such copies, or 
  7. --  revisions thereof, must display this notice unaltered. 
  8. --  This code contains trade secrets of Real-Time Innovations, Inc. 
  9.  
  10.  
  11.  
  12. limited with DDS.Subscriber; 
  13. with DDS.TopicDescription; 
  14. with DDS.DataReaderListener; 
  15. with DDS.QueryCondition; 
  16. with DDS.ReadCondition; 
  17. with DDS.Domain_Entity; 
  18. with DDS.MetpTypeSupport; 
  19.  
  20. --  <dref>DataReader</dref> 
  21. package DDS.DataReader is 
  22.  
  23.    type Ref is limited interface and DDS.Domain_Entity.Ref; 
  24.    type Ref_Access is access all Ref'Class; 
  25.  
  26.    --  Allows the application to: 
  27.    --   (1) declare the data it wishes to receive (i.e. make a subscription) and 
  28.    --   (2) access the data received by the attached DDS.Subscriber. 
  29.    -- 
  30.    --  A DDS.DataReader refers to exactly one DDS.TopicDescription 
  31.    --  (either a DDS.Topic, a DDS.ContentFilteredTopic or a DDS.MultiTopic) 
  32.    --  that identifies the data to be read. 
  33.    --  The subscription has a unique resulting type. The data-reader may give 
  34.    --  access to several instances of the resulting type, 
  35.    --  which can be distinguished from each other by their key. 
  36.    -- 
  37.    --  DDS.DataReader is an abstract class. 
  38.    --  It must be specialised for each particular application data-type 
  39.    --  (see USER_DATA). The additional methods or functions that must be defined 
  40.    --  in the auto-generated class for a hypothetical application type Foo are 
  41.    --  specified in the generic type DDS.example.FooDataReader. 
  42.    -- 
  43.    --  The following operations may be called even if the DDS.DataReader 
  44.    --  is not enabled. Other operations will fail with 
  45.    --  exception RETCODE_NOT_ENABLED if called on a disabled DDS.DataReader: 
  46.    -- 
  47.    --  See also: 
  48.    --      Operations Allowed in Listener Callbacks 
  49.  
  50.    type Ref_Access_Access is access all Ref_Access; 
  51.    type Ref_Access_Array is array (Natural range <>) of aliased Ref_Access; 
  52.  
  53.    procedure Initialize 
  54.      (Self : in out Ref_Access) is null; 
  55.  
  56.    procedure Finalize 
  57.      (Self : in out Ref_Access) is null; 
  58.  
  59.    procedure Copy 
  60.      (Dst : in out Ref_Access; 
  61.       Src : in Ref_Access); 
  62.  
  63.    function Create_Readcondition 
  64.      (Self            : not null access Ref; 
  65.       Sample_States   : in DDS.SampleStateMask; 
  66.       View_States     : in DDS.ViewStateMask; 
  67.       Instance_States : in DDS.InstanceStateMask) 
  68.       return DDS.ReadCondition.Ref_Access is abstract; 
  69.    --  <dref>DataReader_create_readcondition</dref> 
  70.    --  <internal> 
  71.    --  The returned DDS.ReadCondition will be 
  72.    --  attached and belong to the DDS.DataReader. 
  73.    --  </internal> 
  74.  
  75.    function Create_Querycondition 
  76.      (Self             : not null access Ref; 
  77.       Sample_States    : in DDS.SampleStateMask; 
  78.       View_States      : in DDS.ViewStateMask; 
  79.       Instance_States  : in DDS.InstanceStateMask; 
  80.       Query_Expression : in DDS.String; 
  81.       Query_Parameters : in DDS.String_Seq.Sequence) 
  82.       return DDS.QueryCondition.Ref_Access is abstract; 
  83.    --  <dref>DataReader_create_querycondition</dref> 
  84.    --  <internal> 
  85.    --  Not supported (optional>> Creates a DDS.QueryCondition. 
  86.    --  The returned DDS.QueryCondition will be attached 
  87.    --  and belong to the DDS.DataReader. 
  88.    --  Queries and Filters Syntax describes the syntax of 
  89.    --  query_expression and query_parameter 
  90.    --  </internal> 
  91.  
  92.    procedure Delete_Readcondition 
  93.      (Self        : not null access Ref; 
  94.       A_Condition : access DDS.ReadCondition.Ref'Class) is abstract; 
  95.    --  <dref>DataReader_delete_readcondition</dref> 
  96.  
  97.    procedure  Delete_Contained_Entities 
  98.      (Self : not null access Ref) is abstract; 
  99.    --  <dref>DataReader_delete_contained_entities</dref> 
  100.    --  <internal> 
  101.    --  Deletes all the entities that were created by means of the "create" 
  102.    --  operations on the dds.DataReader. 
  103.    --  Deletes all contained dds.ReadCondition and dds.QueryCondition objects. 
  104.    --  The operation will fail with RETCODE_PRECONDITION_NOT_MET if the any of 
  105.    --  the contained entities is in a state where it cannot be deleted. 
  106.    --  Once dds.DataReader.delete_contained_entities completes successfully, 
  107.    --  the application may delete the dds.DataReader, knowing that it has no 
  108.    --  contained dds.ReadCondition and dds.QueryCondition objects. 
  109.    --  </internal> 
  110.  
  111.    procedure Set_Qos 
  112.      (Self : not null access Ref; 
  113.       Qos  : in DDS.DataReaderQoS) is abstract; 
  114.    --  <dref>DataReader_set_qos</dref> 
  115.  
  116.    procedure Set_Qos_With_Profile 
  117.      (Self          : not null access Ref; 
  118.       library_name  : in String; 
  119.       profile_name  : in String) is abstract; 
  120.    procedure Set_Qos_With_Profile 
  121.      (Self          : not null access Ref; 
  122.       library_name  : in Standard.String; 
  123.       profile_name  : in Standard.String) is abstract; 
  124.    --  <dref>DataReader_set_qos_with_profile</dref> 
  125.    --  <internal> 
  126.    --  This operation modifies the QoS of the DDS.DataReader. 
  127.    --  The DataReaderQos.user_data, 
  128.    --      DataReaderQos.deadline, 
  129.    --      DataReaderQos.latency_budget, 
  130.    --      DataReaderQos.time_based_filter, 
  131.    --      DataReaderQos.reader_data_lifecycle 
  132.    --  can be changed. 
  133.    --  The other policies are immutable. 
  134.    --  </internal> 
  135.  
  136.  
  137.    procedure Get_Qos 
  138.      (Self : not null access Ref; 
  139.       Qos  : in out DDS.DataReaderQoS) is abstract; 
  140.    --  <dref>DataReader_get_qos</dref> 
  141.    --  <internal> 
  142.    --  Gets the reader QoS. 
  143.    --  This method may potentially allocate memory depending on the sequences 
  144.    --  contained in some QoS policies 
  145.    --  </internal> 
  146.  
  147.  
  148.    procedure Set_Listener 
  149.      (Self       : not null access Ref; 
  150.       A_Listener : in DDS.DataReaderListener.Ref_Access; 
  151.       Mask       : in DDS.StatusMask) is abstract; 
  152.    --  <dref>DataReader_set_listener</dref> 
  153.    --  <internal> 
  154.    --  Sets the reader listener. 
  155.    --  </internal> 
  156.  
  157.  
  158.    function Get_Listener 
  159.      (Self : not null access Ref) 
  160.       return DDS.DataReaderListener.Ref_Access is abstract; 
  161.    --  <dref>DataReader_get_listener</dref> 
  162.    --  <internal> 
  163.    --  Get the reader listener 
  164.    --  </internal> 
  165.  
  166.    procedure Call_ListnerT 
  167.      (Self       : not null access Ref; 
  168.       A_Listener : in DDS.DataReaderListener.Ref_Access; 
  169.       Mask       : in DDS.StatusMask) is abstract; 
  170.    --  <internal> 
  171.    --  Calls the reader listener. 
  172.    --  </internal> 
  173.  
  174.    function Get_Topicdescription 
  175.      (Self : not null access Ref) 
  176.       return DDS.TopicDescription.Ref_Access is abstract; 
  177.    --  <dref>DataReader_get_topicdescription</dref> 
  178.    --  <internal> 
  179.    --  Returns the dds.TopicDescription associated with the dds.DataReader. 
  180.    --  </internal> 
  181.  
  182.    function Get_Subscriber 
  183.      (Self : not null access Ref) 
  184.       return access DDS.Subscriber.Ref'Class is abstract; 
  185.    --  <dref>DataReader_get_subscriber</dref> 
  186.    --  <internal> 
  187.    --  Returns the dds.Subscriber to which the dds.DataReader belongs. 
  188.    --  </internal> 
  189.  
  190.  
  191.    procedure Get_Sample_Rejected_Status 
  192.      (Self   : not null access Ref; 
  193.       Status : in out DDS.SampleRejectedStatus) is abstract; 
  194.    --  <dref>DataReader_get_sample_rejected_status</dref> 
  195.    --  <internal> 
  196.    --  Return the StatusKind.SAMPLE_REJECTED_STATUS communication status. 
  197.    --  </internal> 
  198.  
  199.    procedure Get_Liveliness_Changed_Status 
  200.      (Self : not null access Ref; 
  201.       Status : in out DDS.LivelinessChangedStatus) is abstract; 
  202.    --  <dref>DataReader_get_liveliness_changed_status</dref> 
  203.    --  <internal> 
  204.    --  Returns the StatusKind.LIVELINESS_CHANGED_STATUS communication status. 
  205.    --  </internal> 
  206.  
  207.    procedure Get_Requested_Deadline_Missed_Status 
  208.      (Self : not null access Ref; 
  209.       Status : in out DDS.RequestedDeadlineMissedStatus) is abstract; 
  210.    --  <dref>DataReader_get_requested_deadline_missed_status</dref> 
  211.    --  <internal> 
  212.    --  Returns the StatusKind.REQUESTED_DEADLINE_MISSED_STATUS 
  213.    --  communication status. 
  214.    --  </internal> 
  215.  
  216.    procedure Get_Requested_Incompatible_Qos_Status 
  217.      (Self : not null access Ref; 
  218.       Status : in out DDS.RequestedIncompatibleQosStatus) is abstract; 
  219.    --  <dref>DataReader_get_requested_incompatible_qos_status</dref> 
  220.    --  <internal> 
  221.    --  Returns the StatusKind.REQUESTED_INCOMPATIBLE_QOS_STATUS 
  222.    --  communication status 
  223.    --  </internal> 
  224.  
  225.    procedure Get_Subscription_Matched_Status 
  226.      (Self : not null access Ref; 
  227.       Status : in out DDS.SubscriptionMatchedStatus) is abstract; 
  228.    --  <dref>DataReader_get_subscription_matched_status</dref> 
  229.    --  <internal> 
  230.    --  Returns the StatusKind.SUBSCRIPTION_MATCHED_STATUS communication status. 
  231.    --  </internal> 
  232.  
  233.    procedure Get_Sample_Lost_Status 
  234.      (Self : not null access Ref; 
  235.       Status : in out DDS.SampleLostStatus) is abstract; 
  236.    --  <dref>DataReader_get_sample_lost_status</dref> 
  237.    --  <internal> 
  238.    --  Returns the StatusKind.SAMPLE_LOST_STATUS_STATUS communication status 
  239.    --  </internal> 
  240.  
  241.    procedure Get_Datareader_Cache_Status 
  242.      (Self : not null access Ref; 
  243.       Status : in out DDS.DataReaderCacheStatus) is abstract; 
  244.    --  <dref>DataReader_get_datareader_cache_status</dref> 
  245.    --  <internal> 
  246.    --  Returns the StatusKind.DATA_READER_CACHE_STATUS communication status 
  247.    --  </internal> 
  248.  
  249.    procedure Get_Datareader_Protocol_Status 
  250.      (Self : not null access Ref; 
  251.       Status : in out DDS.DataReaderProtocolStatus) is abstract; 
  252.    --  <dref>DataReader_get_datareader_protocol_status</dref> 
  253.    --  <internal> 
  254.    --  Returns the StatusKind.DATA_READER_PROTOCOL_STATUS communication status 
  255.    --  </internal> 
  256.  
  257.    procedure Get_Matched_Publication_Datareader_Protocol_Status 
  258.      (Self : not null access Ref; 
  259.       Status : in out DDS.DataReaderProtocolStatus; 
  260.       Publication_Handle : not null access DDS.InstanceHandle_T) is abstract; 
  261.    --  <dref>DataReader_get_matched_publication_datareader_protocol_status</dref> 
  262.    --  <internal> 
  263.    --  Returns the StatusKind.DATA_READER_PROTOCOL_STATUS communication status 
  264.    --  for this reader, per matched publication identified by the 
  265.    --  Publication_Handle. 
  266.    --  </internal> 
  267.  
  268.    procedure Wait_For_Historical_Data 
  269.      (Self     : not null access Ref; 
  270.       Max_Wait : in DDS.Duration_T) is abstract; 
  271.    --  <dref>DataReader_wait_for_historical_data</dref> 
  272.    --  <internal> 
  273.    --  Waits until all "historical" data is received for dds.DataReader entities 
  274.    --  that have a non-VOLATILE PERSISTENCE Qos kind. 
  275.    --  This operation is intended only for dds.DataReader entities that have a 
  276.    --  non-VOLATILE PERSISTENCE QoS kind. 
  277.    --  As soon as an application enables a non-VOLATILE dds.DataReader, it will 
  278.    --  start receiving both "historical" data, i.e. the data that was written 
  279.    --  prior to the time the dds.DataReader joined the domain, as well as any 
  280.    --  new data written by the dds.DataWriter entities. 
  281.    --  There are situations where the application logic may require the 
  282.    --  application to wait until all "historical" data is received. 
  283.    --  This is the purpose of the dds.DataReader.wait_for_historical_data operations. 
  284.    --  The operation dds.DataReader.wait_for_historical_data blocks the calling 
  285.    --  thread until either all "historical" data is received, or else duration 
  286.    --  specified by the max_wait parameter clapses, whichever happens first. 
  287.    --  A successful completion indicates that all the "historical" data was 
  288.    --  "received"; timing out indicates that max_wait elapsed before all the 
  289.    --  data was received 
  290.    --  </internal> 
  291.  
  292.  
  293.    function Get_Matched_Publications 
  294.      (Self    : not null access Ref) 
  295.       return DDS.InstanceHandle_Seq.Sequence is abstract; 
  296.    --  <dref>DataReader_get_matched_publications</dref> 
  297.    --  <internal> 
  298.    --  Retrieve the list of publications currently "associated" with this 
  299.    --  DDS.DataReader. 
  300.    --  Matching publications are those in the same domain that have a matching 
  301.    --  DDS.Topic, compatible QoS common partition that the DDS.DomainParticipant 
  302.    --  has not indicated should be "ignored" by means of the 
  303.    --  DDS.DomainParticipant.ignore_publication operation. 
  304.    --  The handles returned in the publication_handles' list are the ones that 
  305.    --  are used by the DDS implementation to locally identify the corresponding 
  306.    --  matched DDSDataWriter entities. 
  307.    --  These handles match the ones that appear in the instance_handle field 
  308.    --  of the DDS.SampleInfo when reading the 
  309.    --  PublicationBuiltinTopicDataTypeSupport.PUBLICATION_TOPIC_NAME builtin topic 
  310.    --  The sequence will be grown if the sequence has ownership and the system 
  311.    --  has the corresponding resources. Use a sequence without ownership to 
  312.    --  avoid dynamic memory allocation. If the sequence is too small to 
  313.    --  store all the matches and the system can not resize the sequence, 
  314.    --  this method will fail with RETCODE_OUT_OF_RESOURCES. 
  315.    --  The maximum number of matches possible is configured with 
  316.    --  DDS.DomainParticipantResourceLimitsQosPolicy. 
  317.    --  You can use a zero-maximum sequence without ownership to quickly check 
  318.    --  whether there are any matches without allocating any memory. 
  319.    --  </internal> 
  320.  
  321.    function Get_Matched_Publication_Data 
  322.      (Self               : not null access Ref; 
  323.       Publication_Handle : not null access DDS.InstanceHandle_T) 
  324.       return DDS.PublicationBuiltinTopicData is abstract; 
  325.    --  <dref>DataReader_get_matched_publication_data</dref> 
  326.    --  <internal> 
  327.    --  This operation retrieves the information on a publication that is 
  328.    --  currently "associated" with the dds.DataReader. 
  329.    --  Publication with a matching dds.Topic, compatible QoS and common 
  330.    --  partition that the application has not indicated should be "ignored" 
  331.    --  by means of the dds.DomainParticipant.ignore_publication operation. 
  332.    --  The publication_handle must correspond to a publication currently 
  333.    --  associated with the dds.DataReader. Otherwise, the operation will fail 
  334.    --   with RETCODE_BAD_PARAMETER. 
  335.    --  use the operation dds.DataReader.get_matched_publications to find the 
  336.    --  publications that are currently matched with the DDS.DataReader. 
  337.    --  </internal> 
  338.  
  339.  
  340.    procedure  call_listener 
  341.      (Self  : not null access Ref; 
  342.       mask  : StatusMask) is abstract; 
  343.  
  344.    procedure  set_liveliness_changed_status 
  345.      (Self : not null access Ref; 
  346.       To  : LivelinessChangedStatus) is abstract; 
  347.  
  348. end DDS.DataReader;