1. --  (c) Copyright, Real-Time Innovations, $Date:: 2012-02-16 #$ 
  2. --  All rights reserved. 
  3. -- 
  4. --  No duplications, whole or partial, manual or electronic, may be made 
  5. --  without express written permission.  Any such copies, or 
  6. --  revisions thereof, must display this notice unaltered. 
  7. --  This code contains trade secrets of Real-Time Innovations, Inc. 
  8.  
  9. --  ============================================================================ 
  10. -- 
  11. --         WARNING: THIS FILE IS AUTO-GENERATED. DO NOT MODIFY. 
  12. -- 
  13. --  This file was generated from .idl using "rtiddsgen". 
  14. --  The rtiddsgen tool is part of the RTI Data Distribution Service distribution. 
  15. --  For more information, type 'rtiddsgen -help' at a command shell 
  16. --  or consult the RTI Data Distribution Service manual. 
  17. -- 
  18. --  ============================================================================ 
  19.  
  20. pragma Warnings (Off); --  Since this is autogenerated code. 
  21.  
  22. with DDS.DataReader; 
  23. with DDS.DataReader_Impl; 
  24. with DDS.ReadCondition; 
  25.  
  26. with DDS; use DDS; 
  27. pragma Warnings (On); 
  28.  
  29. --  <dref>SubscriptionBuiltinTopicDataDataReader</dref> 
  30. package DDS.SubscriptionBuiltinTopicData_DataReader is 
  31.  
  32.    type Ref is new Standard.DDS.DataReader_Impl.Ref with null record; 
  33.    type Ref_Access is access all Ref'Class; 
  34.  
  35.    procedure Read 
  36.      (This            : not null access Ref; 
  37.       Received_Data   : not null access SubscriptionBuiltinTopicData_Seq.Sequence; 
  38.       Info_Seq        : not null access Standard.DDS.SampleInfo_Seq.Sequence; 
  39.       Max_Samples     : in Standard.DDS.Long := Standard.DDS.LENGTH_UNLIMITED; 
  40.       Sample_States   : in Standard.DDS.SampleStateMask := Standard.DDS.ANY_SAMPLE_STATE; 
  41.       View_States     : in Standard.DDS.ViewStateMask := Standard.DDS.ANY_VIEW_STATE; 
  42.       Instance_States : in Standard.DDS.InstanceStateMask := Standard.DDS.ANY_INSTANCE_STATE); 
  43.    --  <internal> 
  44.    --  Access a collection of data samples from the DDS_DataReader. 
  45.    --  This operation offers the same functionality and API as take except that the 
  46.    --  samples returned remain in the DDS_DataReader such that they can be retrieved 
  47.    --  again by means of a read or take operation. 
  48.    --  Please refer to the documentation of take for details on the number of samples 
  49.    --  returned within the received_data and info_seq as well as the order in which 
  50.    --  the samples appear in these sequences. 
  51.    --  The act of reading a sample changes its sample_state to DDS_READ_SAMPLE_STATE. 
  52.    --  If the sample belongs to the most recent generation of the instance, 
  53.    --  it will also set the view_state of the instance to be DDS_NOT_NEW_VIEW_STATE. 
  54.    --  It will not affect the instance_state of the instance. 
  55.    --  Important: If the samples "returned" by this function are loaned from 
  56.    --  RTI Data Distribution Service (see take for more information on memory loaning), 
  57.    --  it is important that their contents not be changed. 
  58.    --  Because the memory in which the data is stored belongs to the middleware, 
  59.    --  any modifications made to the data will be seen the next time the same samples 
  60.    --  are read or taken; 
  61.    --  the samples will no longer reflect the state that was received from the network. 
  62.    --  </internal> 
  63.  
  64.  
  65.    procedure Take 
  66.      (This            : not null access Ref; 
  67.       Received_Data   : not null access SubscriptionBuiltinTopicData_Seq.Sequence; 
  68.       Info_Seq        : not null access Standard.DDS.SampleInfo_Seq.Sequence; 
  69.       Max_Samples     : in Standard.DDS.Long := Standard.DDS.LENGTH_UNLIMITED; 
  70.       Sample_States   : in Standard.DDS.SampleStateMask := Standard.DDS.ANY_SAMPLE_STATE; 
  71.       View_States     : in Standard.DDS.ViewStateMask := Standard.DDS.ANY_VIEW_STATE; 
  72.       Instance_States : in Standard.DDS.InstanceStateMask := Standard.DDS.ANY_INSTANCE_STATE); 
  73.    --  <internal> 
  74.    --  Access a collection of data-samples from the DataReader. 
  75.    --  The operation will return the list of samples received by the 
  76.    --  DataReader since the last DataReader.take operation that match the 
  77.    --  specified SampleStateMask, ViewStateMask and InstanceStateMask. 
  78.    --  This operation may fail with an exception if 
  79.    --  DataReaderResourceLimitsQosPolicy::max_outstanding_reads limit 
  80.    --  has been exceeded. 
  81.    --  The actual number of samples returned depends on the information that has 
  82.    --  been received by the middleware as well as the HistoryQosPolicy, 
  83.    --  ResourceLimitsQosPolicy, DataReaderResourceLimitsQosPolicy and the 
  84.    --  characteristics of the data-type that is associated with the DataReader: 
  85.    --    * In the case where the HistoryQosPolicy::kind is KEEP_LAST_HISTORY_QOS, 
  86.    --      the call will return at most HistoryQosPolicy::depth samples per instance. 
  87.    --    * The maximum number of samples returned is limited by 
  88.    --       ResourceLimitsQosPolicy::max_samples, and by 
  89.    --       DataReaderResourceLimitsQosPolicy::max_samples_per_read. 
  90.    --    * For multiple instances, the number of samples returned is additionally 
  91.    --      limited by the product 
  92.    --       (ResourceLimitsQosPolicy::max_samples_per_instance * 
  93.    --        ResourceLimitsQosPolicy::max_instances) 
  94.    --    * If DataReaderResourceLimitsQosPolicy::max_infos is limited, 
  95.    --      the number of samples returned may also be limited if insufficient 
  96.    --  SampleInfo resources are available. 
  97.    --  If the read or take succeeds and the number of samples returned has been 
  98.    --  limited (by means of a maximum limit, as listed above, or insufficient 
  99.    --  SampleInfo resources), 
  100.    --  the call will complete successfully and provide those samples the reader 
  101.    --  is able to return. The user may need to make additional calls, 
  102.    --  or return outstanding loaned buffers in the case of insuffificient resources, 
  103.    --  in order to access remaining samples. 
  104.    --  Note that in the case where the Topic associated with the DataReader 
  105.    --  is bound to a data-type that has no key definition, 
  106.    --  then there will be at most one instance in the DataReader. 
  107.    --  So the per-sample limits will apply. 
  108.    --  The act of taking a sample removes it from Data Distribution Service 
  109.    --  so it cannot be read or taken again. 
  110.    --  If the sample belongs to the most recent generation of the instance, 
  111.    --  it will also set the view_state of the sample's instance to NOT_NEW_VIEW_STATE. 
  112.    --  It will not affect the instance_state of the sample's instance. 
  113.    --  After DataReader.take completes, received_data and info_seq will be of 
  114.    --  the same length and contain the received data. 
  115.    --  If the sequences are empty (maximum size equal 0) when the take is called, 
  116.    --  the samples returned in the received_data and the corresponding 
  117.    --  info_seq are 'loaned' to the application from buffers provided by the DataReader. 
  118.    --  The application can use them as desired and has guaranteed exclusive access to them. 
  119.    --  Once the application completes its use of the samples it must 'return the loan' 
  120.    --  to the DataReader by calling the DataReader.return_loan operation. 
  121.    --  Note: 
  122.    --   While you must call Return_Loan at some point, you do not have to do so 
  123.    --   before the next take call. 
  124.    --  However, failure to return the loan will eventually deplete the DataReader 
  125.    --  of the buffers it needs to receive new samples and eventually samples will 
  126.    --  start to be lost. The total number of buffers available to the DataReader 
  127.    --  is specified by the ResourceLimitsQosPolicy and the DataReaderResourceLimitsQosPolicy. 
  128.    --  If the sequences are not empty (maximum size not equal 0) when the take is called, 
  129.    --  samples are copied to received_data and info_seq. The application will not 
  130.    --  need to call return_loan. 
  131.    --  The order of the samples returned to the caller depends on the PresentationQosPolicy. 
  132.    --      * If PresentationQosPolicy::access_scope is INSTANCE_PRESENTATION_QOS, 
  133.    --        the returned collection is a list where samples belonging to the 
  134.    --        same data instance are consecutive. 
  135.    --      * If PresentationQosPolicy::access_scope is TOPIC_PRESENTATION_QOS and 
  136.    --        PresentationQosPolicy::ordered_access is set to BOOLEAN_FALSE, 
  137.    --        then returned collection is a list where samples belonging to 
  138.    --        the same data instance are consecutive. 
  139.    --      * If PresentationQosPolicy::access_scope is TOPIC_PRESENTATION_QOS and 
  140.    --        PresentationQosPolicy::ordered_access is set to TRUE, then the 
  141.    --        returned collection is a list were the relative order of samples is 
  142.    --        preserved also accross different instances. Note that samples belonging 
  143.    --        to the same instance may or may not be consecutive. This is because 
  144.    --        to preserve order it may be necessary to mix samples from different instances. 
  145.    --      * If PresentationQosPolicy::access_scope is GROUP_PRESENTATION_QOS and 
  146.    --           PresentationQosPolicy::ordered_access is set to FALSE, then returned 
  147.    --        collection is a list where samples belonging to the same data instance 
  148.    --        are consecutive. [Not supported (optional)] 
  149.    --      * If PresentationQosPolicy::access_scope is GROUP_PRESENTATION_QOS and 
  150.    --           PresentationQosPolicy::ordered_access is set to TRUE, 
  151.    --        then the returned collection contains at most one sample. 
  152.    --        The difference in this case is due to the fact that is required that 
  153.    --        the application is able to read samples belonging to different DataReader 
  154.    --        objects in a specific order. [Not supported (optional)] 
  155.    --  In any case, the relative order between the samples of one instance is consistent 
  156.    --  with the DESTINATION_ORDER policy: 
  157.    --    * If DestinationOrderQosPolicy::kind is BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS, 
  158.    --      samples belonging to the same instances will appear in the relative order 
  159.    --     in which there were received (FIFO, earlier samples ahead of the later samples). 
  160.    --    * If DestinationOrderQosPolicy::kind is BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS, 
  161.    --      samples belonging to the same instances will appear in the relative order 
  162.    --      implied by the source_timestamp (FIFO, smaller values of source_timestamp 
  163.    --      ahead of the larger values). 
  164.    --  If the DataReader has no samples that meet the constraints, the function 
  165.    --  will fail with exception NO_DATA. 
  166.    --  In addition to the collection of samples, the read and take operations also 
  167.    --   use a collection of SampleInfo structures. 
  168.    --  SEQUENCES USAGE IN TAKE AND READ 
  169.    --  The initial (input) properties of the received_data and info_seq collections 
  170.    --  will determine the precise behavior of the read or take operation. 
  171.    --  For the purposes of this description, the collections are modeled as having 
  172.    --  these properties: 
  173.    --      * whether the collection container owns the memory of the elements 
  174.    --        within (owns, see Seq_has_ownership) 
  175.    --      * the current-length (len, see Seq_get_length) 
  176.    --      * the maximum length (max_len, see Seq_get_maximum) 
  177.    -- 
  178.    --  The initial values of the owns, len and max_len properties for the received_data 
  179.    --  and info_seq collections govern the behavior of the read and take operations 
  180.    --  as specified by the following rules : 
  181.    --   1. The values of owns, len and max_len properties for the two collections must be identical. 
  182.    --      Otherwise read/take will fail with PRECONDITION_NOT_MET. 
  183.    --   2. On successful output, the values of owns, len and max_len 
  184.    --      will be the same for both collections. 
  185.    --   3. If the initial max_len==0, then the received_data and info_seq 
  186.    --      collections will be filled with elements that are loaned by the DataReader. 
  187.    --      On output, owns will be FALSE, len will be set to the number of values returned, 
  188.    --      and max_len will be set to a value verifying max_len >= len. 
  189.    --      The use of this variant allows for zero-copy access to the data and 
  190.    --      the application will need to return the loan to the DataWriter using return_loan. 
  191.    --   4. If the initial max_len>0 and owns==FALSE, then the read or take operation 
  192.    --      will fail with exception PRECONDITION_NOT_MET. 
  193.    --      This avoids the potential hard-to-detect memory leaks caused by an 
  194.    --      application forgetting to return the loan. 
  195.    --   5. If initial max_len>0 and owns==TRUE, then the read or take operation will copy 
  196.    --      the received_data values and SampleInfo values into the elements already 
  197.    --      inside the collections. On output, owns will be TRUE, len will be set to 
  198.    --      the number of values copied and max_len will remain unchanged. 
  199.    --      The use of this variant forces a copy but the application can control 
  200.    --      where the copy is placed and the application will not need to return the loan. 
  201.    --      The number of samples copied depends on the relative values of max_len and max_samples: 
  202.    --    * If max_samples == LENGTH_UNLIMITED, then at most max_len values will be copied. 
  203.    --      The use of this variant lets the application limit the number of samples 
  204.    --      returned to what the sequence can accommodate. 
  205.    --    * If max_samples <= max_len, then at most max_samples values will be copied. 
  206.    --      The use of this variant lets the application limit the number of samples 
  207.    --      returned to fewer that what the sequence can accommodate. 
  208.    --    * If max_samples > max_len, then the read or take operation will fail with 
  209.    --      exception PRECONDITION_NOT_MET. This avoids the potential confusion where 
  210.    --      the application expects to be able to access up to max_samples, but that 
  211.    --      number can never be returned, even if they are available in the DataReader, 
  212.    --      because the output sequence cannot accommodate them. 
  213.    --  As described above, upon completion, the received_data and info_seq collections 
  214.    --  may contain elements loaned from the DataReader. 
  215.    --  If this is the case, the application will need to use return_loan to return 
  216.    --  the loan once it is no longer using the received_data in the collection. 
  217.    --  When return_loan completes, the collection will have owns=FALSE and max_len=0. 
  218.    --  The application can determine whether it is necessary to return the loan or not 
  219.    --  based on how the state of the collections when the read/take operation was called 
  220.    --  or by accessing the owns property. However, in many cases it may be simpler to 
  221.    --  always call return_loan, as this operation is harmless 
  222.    --  (i.e., it leaves all elements unchanged) if the collection does not have a loan. 
  223.    --  To avoid potential memory leaks, the implementation of the data and SampleInfo 
  224.    --  collections should disallow changing the length of a collection for which owns==FALSE. 
  225.    --  Furthermore, deleting a collection for which owns==FALSE should be considered an error. 
  226.    --  On output, the collection of data values and the collection of SampleInfo structures 
  227.    --  are of the same length and are in a one-to-one correspondence. 
  228.    --  Each SampleInfo provides information, such as the source_timestamp, 
  229.    --  the sample_state, view_state, and instance_state, etc., about the corresponding sample. 
  230.    -- 
  231.    --  Some elements in the returned collection may not have valid data. 
  232.    --  If the instance_state in the SampleInfo is NOT_ALIVE_DISPOSED_INSTANCE_STATE 
  233.    --  or NOT_ALIVE_NO_WRITERS_INSTANCE_STATE, then the last sample for that instance 
  234.    --  in the collection (that is, the one whose SampleInfo has sample_rank==0) 
  235.    --  does not contain valid data. 
  236.    --  Samples that contain no data do not count towards the limits imposed by the 
  237.    --  ResourceLimitsQosPolicy. The act of reading/taking a sample sets its 
  238.    --  sample_state to READ_SAMPLE_STATE. 
  239.    --  If the sample belongs to the most recent generation of the instance, 
  240.    --  it will also set the view_state of the instance to NOT_NEW_VIEW_STATE. 
  241.    --  It will not affect the instance_state of the instance. 
  242.    --  This operation must be provided on the specialized class that is generated for 
  243.    --  the particular application data-type that is being read. If the DataReader has 
  244.    --  no samples that meet the constraints, the operations fails with exception NO_DATA. 
  245.    --  </internal> 
  246.  
  247.  
  248.    procedure Read_W_Condition 
  249.      (This          : not null access Ref; 
  250.       Received_Data : not null access SubscriptionBuiltinTopicData_Seq.Sequence; 
  251.       Info_Seq      : not null access Standard.DDS.SampleInfo_Seq.Sequence; 
  252.       Max_Samples   : in Standard.DDS.Long := Standard.DDS.LENGTH_UNLIMITED; 
  253.       Condition     : access Standard.DDS.ReadCondition.Ref'Class); 
  254.    --  <internal> 
  255.    --  Accesses via read the samples that match the criteria specified in the ReadCondition. 
  256.    --  This operation is especially useful in combination with QueryCondition to 
  257.    --  filter data samples based on the content. 
  258.    --  The specified ReadCondition must be attached to the DataReader; 
  259.    --  otherwise the operation will fail with exception PRECONDITION_NOT_MET. 
  260.    --  In case the ReadCondition is a plain ReadCondition and not the 
  261.    --  specialized QueryCondition, the operation is equivalent to calling read 
  262.    --  and passing as sample_states, view_states and instance_states the value of 
  263.    --  the corresponding attributes in the read_condition. 
  264.    --  Using this operation, the application can avoid repeating the same parameters 
  265.    --  specified when creating the ReadCondition. 
  266.    --  The samples are accessed with the same semantics as read. 
  267.    --  If the DataReader has no samples that meet the constraints, 
  268.    --  the operation will fail with exception RETCODE_NO_DATA. 
  269.    --  </internal> 
  270.  
  271.  
  272.    procedure Take_W_Condition 
  273.      (This          : not null access Ref; 
  274.       Received_Data : not null access SubscriptionBuiltinTopicData_Seq.Sequence; 
  275.       Info_Seq      : not null access Standard.DDS.SampleInfo_Seq.Sequence; 
  276.       Max_Samples   : in Standard.DDS.Long := Standard.DDS.LENGTH_UNLIMITED; 
  277.       Condition     : access Standard.DDS.ReadCondition.Ref'Class); 
  278.    --  <internal> 
  279.    --  Analogous to read_w_condition except it accesses samples via the take operation. 
  280.    --  This operation is analogous to read_w_condition except that it accesses 
  281.    --  samples via the take operation. 
  282.    --  The specified ReadCondition must be attached to the DataReader; 
  283.    --  otherwise the operation will fail with exception PRECONDITION_NOT_MET. 
  284.    --  The samples are accessed with the same semantics as take. 
  285.    --  This operation is especially useful in combination with QueryCondition 
  286.    --  to filter data samples based on the content. 
  287.    --  If the DataReader has no samples that meet the constraints, 
  288.    --  the function will fail with exception NO_DATA. 
  289.    --  </internal> 
  290.  
  291.  
  292.    procedure Read_Next_Sample 
  293.      (This          : not null access Ref; 
  294.       Received_Data : not null SubscriptionBuiltinTopicData_Access; 
  295.       Sample_Info   : not null access Standard.DDS.SampleInfo); 
  296.    --  <internal> 
  297.    --  Copies the next not-previously-accessed data value from the DataReader. 
  298.    --  This operation copies the next not-previously-accessed data value from the DataReader. 
  299.    --  This operation also copies the corresponding SampleInfo. The implied order among 
  300.    --  the samples stored in the DataReader is the same as for the read operation. 
  301.    --  The read_next_sample operation is semantically equivalent to the read operation, 
  302.    --  where the input data sequences has max_len=1, the sample_states=NOT_READ, 
  303.    --  the view_states=ANY_VIEW_STATE, and the instance_states=ANY_INSTANCE_STATE. 
  304.    --  The read_next_sample operation provides a simplified API to 'read' samples, 
  305.    --  avoiding the need for the application to manage sequences and specify states. 
  306.    --  If there is no unread data in the DataReader, the operation will fail with 
  307.    --  exception NO_DATA and nothing is copied. 
  308.    --  </internal> 
  309.  
  310.  
  311.    procedure Take_Next_Sample 
  312.      (This          : not null access Ref; 
  313.       Received_Data : not null SubscriptionBuiltinTopicData_Access; 
  314.       Sample_Info   : not null access Standard.DDS.SampleInfo); 
  315.    --  <internal> 
  316.    --  Copies the next not-previously-accessed data value from the DataReader. 
  317.    --  This operation copies the next not-previously-accessed data value from the DataReader 
  318.    --  and 'removes' it from the DataReader so that it is no longer accessible. 
  319.    --  This operation also copies the corresponding SampleInfo. 
  320.    --  This operation is analogous to the read_next_sample except for the fact 
  321.    --  that the sample is removed from the DataReader. 
  322.    --  The take_next_sample operation is semantically equivalent to the take operation, 
  323.    --  where the input data sequences has max_len=1, the sample_states=NOT_READ, 
  324.    --  the view_states=ANY_VIEW_STATE, and the instance_states=ANY_INSTANCE_STATE. 
  325.    --  The read_next_sample operation provides a simplified API to 'take' samples, 
  326.    --  avoiding the need for the application to manage sequences and specify states. 
  327.    --  If tere is no unread data in the DataReader, the operation will fail 
  328.    --  with exception NO_DATA and nothing is copied. 
  329.    --  </internal> 
  330.  
  331.  
  332.    procedure Read_Instance 
  333.      (This            : not null access Ref; 
  334.       Received_Data   : not null access SubscriptionBuiltinTopicData_Seq.Sequence; 
  335.       Info_Seq        : not null access Standard.DDS.SampleInfo_Seq.Sequence; 
  336.       Max_Samples     : in Standard.DDS.Long := Standard.DDS.LENGTH_UNLIMITED; 
  337.       A_Handle        : access constant Standard.DDS.InstanceHandle_T; 
  338.       Sample_States   : in Standard.DDS.SampleStateMask := Standard.DDS.ANY_SAMPLE_STATE; 
  339.       View_States     : in Standard.DDS.ViewStateMask := Standard.DDS.ANY_VIEW_STATE; 
  340.       Instance_States : in Standard.DDS.InstanceStateMask := Standard.DDS.ANY_INSTANCE_STATE); 
  341.    --  <internal> 
  342.    --  Access a collection of data samples from the DataReader. 
  343.    --  This operation accesses a collection of data values from the DataReader. 
  344.    --  The behavior is identical to read, except that all samples returned belong 
  345.    --  to the single specified instance whose handle is a_handle. 
  346.    --  Upon successful completion, the data collection will contain samples all 
  347.    --  belonging to the same instance. The corresponding SampleInfo verifies 
  348.    --  SampleInfo::instance_handle == a_handle. 
  349.    --  The read_instance operation is semantically equivalent to the read operation, 
  350.    --  except in building the collection, the DataReader will check that the sample 
  351.    --  belongs to the specified instance and otherwise it will not place the sample 
  352.    --  in the returned collection. 
  353.    --  The behavior of the read_instance operation follows the same rules as the 
  354.    --  read operation regarding the pre-conditions and post-conditions for the received_data 
  355.    --  and sample_info. Similar to the read, the read_instance operation may 'loan' elements 
  356.    --  to the output collections, which must then be returned by means of return_loan. 
  357.    --  Similar to the read, this operation must be provided on the specialized class that 
  358.    --  is generated for the particular application data-type that is being taken. 
  359.    --  If the DataReader has no samples that meet the constraints, 
  360.    --  the function will fail with RETCODE_NO_DATA. 
  361.    --  This operation may fail with RETCODE_BAD_PARAMETER if the InstanceHandle_t 
  362.    --  a_handle does not correspond to an existing data-object known to the DataReader. 
  363.    --  </internal> 
  364.  
  365.  
  366.    procedure Take_Instance 
  367.      (This            : not null access Ref; 
  368.       Received_Data   : not null access SubscriptionBuiltinTopicData_Seq.Sequence; 
  369.       Info_Seq        : not null access Standard.DDS.SampleInfo_Seq.Sequence; 
  370.       Max_Samples     : in Standard.DDS.Long := Standard.DDS.LENGTH_UNLIMITED; 
  371.       A_Handle        : access constant Standard.DDS.InstanceHandle_T; 
  372.       Sample_States   : in Standard.DDS.SampleStateMask := Standard.DDS.ANY_SAMPLE_STATE; 
  373.       View_States     : in Standard.DDS.ViewStateMask := Standard.DDS.ANY_VIEW_STATE; 
  374.       Instance_States : in Standard.DDS.InstanceStateMask := Standard.DDS.ANY_INSTANCE_STATE); 
  375.    --  <internal> 
  376.    --  Access a collection of data samples from the DataReader. 
  377.    --  This operation accesses a collection of data values from the DataReader. 
  378.    --  The behavior is identical to take, except for that all samples returned belong 
  379.    --  to the single specified instance whose handle is a_handle. 
  380.    --  The semantics are the same for the take operation, except in building the collection, 
  381.    --  the DataReader will check that the sample belongs to the specified instance, 
  382.    --  and otherwise it will not place the sample in the returned collection. 
  383.    --  The behavior of the take_instance operation follows the same rules as the 
  384.    --  read operation regarding the pre-conditions and post-conditions for the 
  385.    --  received_data and sample_info. Similar to the read, the take_instance operation may 
  386.    --  'loan' elements to the output collections, which must then be returned by means of return_loan. 
  387.    --  Similar to the read, this operation must be provided on the specialized class 
  388.    --  that is generated for the particular application data-type that is being taken. 
  389.    --  If the DataReader has no samples that meet the constraints, the function fails with exception NO_DATA. 
  390.    --  This operation may fail with exception BAD_PARAMETER if the InstanceHandle_t 
  391.    --  a_handle does not correspond to an existing data-object known to the DataReader. 
  392.    --  </internal> 
  393.  
  394.  
  395.    procedure Read_Next_Instance 
  396.      (This            : not null access Ref; 
  397.       Received_Data   : not null access SubscriptionBuiltinTopicData_Seq.Sequence; 
  398.       Info_Seq        : not null access Standard.DDS.SampleInfo_Seq.Sequence; 
  399.       Max_Samples     : in Standard.DDS.Long := Standard.DDS.LENGTH_UNLIMITED; 
  400.       Previous_Handle : access constant Standard.DDS.InstanceHandle_T; 
  401.       Sample_States   : in Standard.DDS.SampleStateMask := Standard.DDS.ANY_SAMPLE_STATE; 
  402.       View_States     : in Standard.DDS.ViewStateMask := Standard.DDS.ANY_VIEW_STATE; 
  403.       Instance_States : in Standard.DDS.InstanceStateMask := Standard.DDS.ANY_INSTANCE_STATE); 
  404.    --  <internal> 
  405.    --  Access a collection of data samples from the DataReader. 
  406.    --  This operation accesses a collection of data values from the DataReader 
  407.    --  where all the samples belong to a single instance. The behavior is similar to 
  408.    --  read_instance, except that the actual instance is not directly specified. 
  409.    --  Rather, the samples will all belong to the 'next' instance with instance_handle 
  410.    --  'greater' than the specified 'previous_handle' that has available samples. 
  411.    --  This operation implies the existence of a total order 'greater-than' relationship 
  412.    --  between the instance handles. The specifics of this relationship are not all 
  413.    --  important and are implementation specific. The important thing is that, 
  414.    --  according to the middleware, all instances are ordered relative to each other. 
  415.    --  This ordering is between the instance handles; It should not depend on the state 
  416.    --  of the instance (e.g. whether it has data or not) and must be defined even for 
  417.    --  instance handles that do not correspond to instances currently managed by the DataReader. 
  418.    --  For the purposes of the ordering, it should be 'as if' each instance handle was 
  419.    --  represented as unique integer. 
  420.    --  The behavior of read_next_instance is 'as if' the DataReader invoked read_instance, 
  421.    --  passing the smallest instance_handle among all the ones that: 
  422.    --   (a) are greater than previous_handle, and 
  423.    --   (b) have available samples (i.e. samples that meet the constraints imposed by the specified states). 
  424.    --  The special value HANDLE_NIL is guaranteed to be 'less than' any valid instance_handle. 
  425.    --  So the use of the parameter value previous_handle == HANDLE_NIL will 
  426.    --   return the samples for the instance which has the smallest instance_handle 
  427.    --  among all the instances that contain available samples. 
  428.    --  The operation read_next_instance is intended to be used in an 
  429.    --  application-driven iteration, where the application starts by passing 
  430.    --  previous_handle == HANDLE_NIL, examines the samples returned, and then uses 
  431.    --  the instance_handle returned in the SampleInfo as the value of the previous_handle 
  432.    --  argument to the next call to read_next_instance. The iteration continues 
  433.    --  until read_next_instance fails with the value exception NO_DATA. 
  434.    --  Note that it is possible to call the read_next_instance operation with a 
  435.    --  previous_handle that does not correspond to an instance currently managed by 
  436.    --  the DataReader. This is because as stated earlier the 'greater-than' relationship 
  437.    --  is defined even for handles not managed by the DataReader. 
  438.    --  One practical situation where this may occur is when an application is iterating 
  439.    --  though all the instances, takes all the samples of a NOT_ALIVE_NO_WRITERS_INSTANCE_STATE 
  440.    --  instance, returns the loan (at which point the instance information may be removed, 
  441.    --  and thus the handle becomes invalid), and tries to read the next instance. 
  442.    --  The behavior of the read_next_instance operation follows the same rules as 
  443.    --  the read operation regarding the pre-conditions and post-conditions for the 
  444.    --  received_data and sample_info. Similar to the read, the read_instance operation may 
  445.    --  'loan' elements to the output collections, which must then be returned by means of return_loan. 
  446.    --  Similar to the read, this operation must be provided on the specialized class 
  447.    --  that is generated for the particular application data-type that is being taken. 
  448.    --  If the DataReader has no samples that meet the constraints, the function 
  449.    --  will fail with exception NO_DATA. 
  450.    --  </internal> 
  451.  
  452.  
  453.    procedure Take_Next_Instance 
  454.      (This            : not null access Ref; 
  455.       Received_Data   : not null access SubscriptionBuiltinTopicData_Seq.Sequence; 
  456.       Info_Seq        : not null access Standard.DDS.SampleInfo_Seq.Sequence; 
  457.       Max_Samples     : in Standard.DDS.Long := Standard.DDS.LENGTH_UNLIMITED; 
  458.       Previous_Handle : access constant Standard.DDS.InstanceHandle_T; 
  459.       Sample_States   : in Standard.DDS.SampleStateMask := Standard.DDS.ANY_SAMPLE_STATE; 
  460.       View_States     : in Standard.DDS.ViewStateMask := Standard.DDS.ANY_VIEW_STATE; 
  461.       Instance_States : in Standard.DDS.InstanceStateMask := Standard.DDS.ANY_INSTANCE_STATE); 
  462.    --  <internal> 
  463.    --  Access a collection of data samples from the DataReader. 
  464.    --  This operation accesses a collection of data values from the DataReader and 
  465.    --  'removes' them from the DataReader. 
  466.    --  This operation has the same behavior as read_next_instance, except that the 
  467.    --  samples are 'taken' from the DataReader such that they are no longer accessible 
  468.    --  via subsequent 'read' or 'take' operations. 
  469.    --  Similar to the operation read_next_instance, it is possible to call take_next_instance 
  470.    --  with a previous_handle that does not correspond to an instance currently managed by the DataReader. 
  471.    --  The behavior of the take_next_instance operation follows the same rules as the 
  472.    --  read operation regarding the pre-conditions and post-conditions for the received_data 
  473.    --  and sample_info. Similar to the read, the take_next_instance operation may 'loan' 
  474.    --  elements to the output collections, which must then be returned by means of return_loan. 
  475.    --  Similar to the read, this operation must be provided on the specialized class that 
  476.    --  is generated for the particular application data-type that is being taken. 
  477.    --  If the DataReader has no samples that meet the constraints, 
  478.    --  the function will fail with exception NO_DATA. 
  479.    --  </internal> 
  480.  
  481.  
  482.    procedure Read_Next_Instance_W_Condition 
  483.      (This            : not null access Ref; 
  484.       Received_Data   : not null access SubscriptionBuiltinTopicData_Seq.Sequence; 
  485.       Info_Seq        : not null access Standard.DDS.SampleInfo_Seq.Sequence; 
  486.       Max_Samples     : in Standard.DDS.Long := Standard.DDS.LENGTH_UNLIMITED; 
  487.       Previous_Handle : access constant Standard.DDS.InstanceHandle_T; 
  488.       Condition       : Standard.DDS.ReadCondition.Ref_Access); 
  489.    --  <internal> 
  490.    --  Accesses via read_next_instance the samples that match the criteria 
  491.    --  specified in the ReadCondition. 
  492.    --  This operation access a collection of data values from the DataReader. 
  493.    --  The behavior is identical to read_next_instance, except that all samples returned satisfy 
  494.    --  the specified condition. In other words, on success, all returned samples 
  495.    --  belong to the same instance, and the instance is the instance with 'smallest' 
  496.    --  instance_handle among the ones that verify: 
  497.    --   (a) instance_handle >= previous_handle, and 
  498.    --   (b) have samples for which the specified ReadCondition evaluates to TRUE. 
  499.    --  Similar to the operation read_next_instance, it is possible to call 
  500.    --  read_next_instance_w_condition with a previous_handle that does not correspond 
  501.    --  to an instance currently managed by the DataReader. 
  502.    --  The behavior of the read_next_instance_w_condition operation follows the same 
  503.    --  rules as the read operation regarding the pre-conditions and post-conditions for 
  504.    --  the received_data and sample_info. Similar to the read, the 
  505.    --  read_next_instance_w_condition operation may 'loan' elements to the output collections, 
  506.    --  which must then be returned by means of return_loan. 
  507.    --  Similar to the read, this operation must be provided on the specialized class that 
  508.    --  is generated for the particular application data-type that is being taken. 
  509.    --  If the DataReader has no samples that meet the constraints, 
  510.    --  the function will fail with exception NO_DATA. 
  511.    --  </internal> 
  512.  
  513.  
  514.    procedure Take_Next_Instance_W_Condition 
  515.      (This            : not null access Ref; 
  516.       Received_Data   : not null access SubscriptionBuiltinTopicData_Seq.Sequence; 
  517.       Info_Seq        : not null access Standard.DDS.SampleInfo_Seq.Sequence; 
  518.       Max_Samples     : in Standard.DDS.Long := Standard.DDS.LENGTH_UNLIMITED; 
  519.       Previous_Handle : access constant Standard.DDS.InstanceHandle_T; 
  520.       Condition       : Standard.DDS.ReadCondition.Ref_Access); 
  521.    --  <internal> 
  522.    --  Accesses via take_next_instance the samples that match the criteria specified 
  523.    --  in the ReadCondition. 
  524.    --  This operation access a collection of data values from the DataReader and 
  525.    --  'removes' them from the DataReader. 
  526.    --  The operation has the same behavior as read_next_instance_w_condition, except 
  527.    --  that the samples are 'taken' from the DataReader such that they are no longer 
  528.    --  accessible via subsequent 'read' or 'take' operations. 
  529.    --  Similar to the operation read_next_instance, it is possible to call 
  530.    --  take_next_instance_w_condition with a previous_handle that does not correspond 
  531.    --  to an instance currently managed by the DataReader. 
  532.    --  The behavior of the take_next_instance_w_condition operation follows the same 
  533.    --  rules as the read operation regarding the pre-conditions and post-conditions 
  534.    --  for the received_data and sample_info. Similar to the read, 
  535.    --  the take_next_instance_w_condition operation may 'loan' elements to the output 
  536.    --  collections, which must then be returned by means of return_loan. 
  537.    --  Similar to the read, this operation must be provided on the specialized class 
  538.    --  that is generated for the particular application data-type that is being taken. 
  539.    --  If the DataReader has no samples that meet the constraints, 
  540.    --  the function will fail with exception NO_DATA. 
  541.    --  </internal> 
  542.  
  543.  
  544.    procedure Return_Loan 
  545.      (This          : not null access Ref; 
  546.       Received_Data : not null access SubscriptionBuiltinTopicData_Seq.Sequence; 
  547.       Info_Seq      : not null access Standard.DDS.SampleInfo_Seq.Sequence); 
  548.    --  <internal> 
  549.    --  Indicates to the DataReader that the application is done accessing the collection 
  550.    --  of received_data and info_seq obtained by some earlier invocation of 
  551.    --  read or take on the DataReader. 
  552.    --  This operation indicates to the DataReader that the application is done accessing 
  553.    --  the collection of received_data and info_seq obtained by some earlier 
  554.    --  invocation of read or take on the DataReader. 
  555.    --  The received_data and info_seq must belong to a single related "pair"; that is, 
  556.    --  they should correspond to a pair returned from a single call to read or take. 
  557.    --  The received_data and info_seq must also have been obtained from the same DataReader 
  558.    --  to which they are returned. If either of these conditions is not met, the operation 
  559.    --  will fail with exception PRECONDITION_NOT_MET. 
  560.    --  The operation return_loan allows implementations of the read and take operations 
  561.    --  to "loan" buffers from the DataReader to the application and in this manner provide 
  562.    --  "zerocopy" access to the data. During the loan, the DataReader will guarantee 
  563.    --  that the data and sample-information are not modified. 
  564.    --  It is not necessary for an application to return the loans immediately after 
  565.    --  the read or take calls. However, as these buffers correspond to internal resources 
  566.    --  inside the DataReader, the application should not retain them indefinitely. 
  567.    --  The use of return_loan is only necessary if the read or take calls "loaned" 
  568.    --  buffers to the application. This only occurs if the received_data and info_Seq 
  569.    --  collections had max_len=0 at the time read or take was called. 
  570.    --  The application may also examine the "owns" property of the collection to determine 
  571.    --  where there is an outstanding loan. However, calling return_loan on a collection 
  572.    --  that does not have a loan is safe and has no side effects. 
  573.    --  If the collections had a loan, upon completion of return_loan, 
  574.    --  the collections will have max_len=0. 
  575.    --  Similar to read, this operation must be provided on the specialized class that 
  576.    --  is generated for the particular application data-type that is being taken. 
  577.    --  </internal> 
  578.  
  579.  
  580.    procedure Get_Key_Value 
  581.      (This       : not null access Ref; 
  582.       Key_Holder : not null SubscriptionBuiltinTopicData_Access; 
  583.       Handle     : access constant Standard.DDS.InstanceHandle_T); 
  584.    --  <internal> 
  585.    --  Retrieve the instance key that corresponds to an instance handle. 
  586.    --  Useful for keyed data types. 
  587.    --  The operation will only fill the fields that form the key inside the key_holder instance. 
  588.    --  For keyed data types, this operation may fail with exception BAD_PARAMETER 
  589.    --  if the handle does not correspond to an existing data-object known to the DDS_DataReader. 
  590.    --  </internal> 
  591.  
  592.  
  593.    function Lookup_Instance 
  594.      (This       : not null access Ref; 
  595.       Key_Holder : not null SubscriptionBuiltinTopicData_Access) return Standard.DDS.InstanceHandle_T; 
  596.    --  <internal> 
  597.    --  Retrieve the instance handle that corresponds to an instance key_holder. 
  598.    --  Useful for keyed data types. 
  599.    --  This operation takes as a parameter an instance and returns a handle that 
  600.    --  can be used in subsequent operations that accept an instance handle as an argument. 
  601.    --  The instance parameter is only used for the purpose of examining the fields that 
  602.    --  define the key. This operation does not register the instance in question. 
  603.    --  If the instance has not been previously registered, or if for any other reason 
  604.    --  the Service is unable to provide an instance handle, 
  605.    --  the Service will return the special value HANDLE_NIL 
  606.    --  </internal> 
  607.  
  608.  
  609.    --  <internal> 
  610.    --  ========================================================================= 
  611.    -- 
  612.    --  Internal Routines not to be used by the application 
  613.    -- 
  614.    --  ========================================================================= 
  615.    --  </internal> 
  616.    function CreateTypedI return Standard.DDS.DataReader.Ref_Access; 
  617.  
  618.    procedure DestroyTypedI 
  619.      (Reader : in out Standard.DDS.DataReader.Ref_Access); 
  620.  
  621. end DDS.SubscriptionBuiltinTopicData_DataReader;