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.

```
 
```

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

```
-- 
```

--         WARNING: THIS FILE IS AUTO-GENERATED. DO NOT MODIFY.

```
-- 
```

--  This file was generated from .idl using "rtiddsgen".

--  The rtiddsgen tool is part of the RTI Data Distribution Service distribution.

--  For more information, type 'rtiddsgen -help' at a command shell

--  or consult the RTI Data Distribution Service manual.

```
-- 
```

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

```
 
```

pragma Warnings (Off); --  Since this is autogenerated code.

```
 
```
```
with DDS.DataReader; 
```
```
with DDS.DataReader_Impl; 
```
```
with DDS.ReadCondition; 
```
```
 
```

with DDSTo API doc
To spec
To body; use DDSTo API doc
To spec
To body;

```
pragma Warnings (On); 
```
```
 
```

--  <dref>PublicationBuiltinTopicDataDataReader</dref>

package DDS.PublicationBuiltinTopicData_DataReaderTo API doc
To body is

```
 
```

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

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

```
 
```
```
   procedure ReadTo API doc
To body 
```

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

      Received_Data   : not null access PublicationBuiltinTopicData_Seq.SequenceTo API doc
To spec;

      Info_Seq        : not null access Standard.DDS.SampleInfo_Seq.SequenceTo API doc
To spec;

      Max_Samples     : in Standard.DDS.LongTo API doc
To spec := Standard.DDS.LENGTH_UNLIMITEDTo API doc
To spec;

      Sample_States   : in Standard.DDS.SampleStateMaskTo API doc
To spec := Standard.DDS.ANY_SAMPLE_STATETo API doc
To spec;

      View_States     : in Standard.DDS.ViewStateMaskTo API doc
To spec := Standard.DDS.ANY_VIEW_STATETo API doc
To spec;

      Instance_States : in Standard.DDS.InstanceStateMaskTo API doc
To spec := Standard.DDS.ANY_INSTANCE_STATETo API doc
To spec);

```
   --  <internal> 
```

   --  Access a collection of data samples from the DDS_DataReader.

   --  This operation offers the same functionality and API as take except that the

   --  samples returned remain in the DDS_DataReader such that they can be retrieved

   --  again by means of a read or take operation.

   --  Please refer to the documentation of take for details on the number of samples

   --  returned within the received_data and info_seq as well as the order in which

   --  the samples appear in these sequences.

   --  The act of reading a sample changes its sample_state to DDS_READ_SAMPLE_STATE.

   --  If the sample belongs to the most recent generation of the instance,

   --  it will also set the view_state of the instance to be DDS_NOT_NEW_VIEW_STATE.

   --  It will not affect the instance_state of the instance.

   --  Important: If the samples "returned" by this function are loaned from

   --  RTI Data Distribution Service (see take for more information on memory loaning),

   --  it is important that their contents not be changed.

   --  Because the memory in which the data is stored belongs to the middleware,

   --  any modifications made to the data will be seen the next time the same samples

```
   --  are read or taken; 
```

   --  the samples will no longer reflect the state that was received from the network.

```
   --  </internal> 
```
```
 
```
```
 
```
```
   procedure TakeTo API doc
To body 
```

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

      Received_Data   : not null access PublicationBuiltinTopicData_Seq.SequenceTo API doc
To spec;

      Info_Seq        : not null access Standard.DDS.SampleInfo_Seq.SequenceTo API doc
To spec;

      Max_Samples     : in Standard.DDS.LongTo API doc
To spec := Standard.DDS.LENGTH_UNLIMITEDTo API doc
To spec;

      Sample_States   : in Standard.DDS.SampleStateMaskTo API doc
To spec := Standard.DDS.ANY_SAMPLE_STATETo API doc
To spec;

      View_States     : in Standard.DDS.ViewStateMaskTo API doc
To spec := Standard.DDS.ANY_VIEW_STATETo API doc
To spec;

      Instance_States : in Standard.DDS.InstanceStateMaskTo API doc
To spec := Standard.DDS.ANY_INSTANCE_STATETo API doc
To spec);

```
   --  <internal> 
```

   --  Access a collection of data-samples from the DataReader.

   --  The operation will return the list of samples received by the

   --  DataReader since the last DataReader.take operation that match the

   --  specified SampleStateMask, ViewStateMask and InstanceStateMask.

   --  This operation may fail with an exception if

   --  DataReaderResourceLimitsQosPolicy::max_outstanding_reads limit

```
   --  has been exceeded. 
```

   --  The actual number of samples returned depends on the information that has

   --  been received by the middleware as well as the HistoryQosPolicy,

   --  ResourceLimitsQosPolicy, DataReaderResourceLimitsQosPolicy and the

   --  characteristics of the data-type that is associated with the DataReader:

   --    * In the case where the HistoryQosPolicy::kind is KEEP_LAST_HISTORY_QOS,

   --      the call will return at most HistoryQosPolicy::depth samples per instance.

   --    * The maximum number of samples returned is limited by

   --       ResourceLimitsQosPolicy::max_samples, and by

   --       DataReaderResourceLimitsQosPolicy::max_samples_per_read.

   --    * For multiple instances, the number of samples returned is additionally

```
   --      limited by the product 
```

   --       (ResourceLimitsQosPolicy::max_samples_per_instance *

   --        ResourceLimitsQosPolicy::max_instances)

   --    * If DataReaderResourceLimitsQosPolicy::max_infos is limited,

   --      the number of samples returned may also be limited if insufficient

   --  SampleInfo resources are available.

   --  If the read or take succeeds and the number of samples returned has been

   --  limited (by means of a maximum limit, as listed above, or insufficient

```
   --  SampleInfo resources), 
```

   --  the call will complete successfully and provide those samples the reader

   --  is able to return. The user may need to make additional calls,

   --  or return outstanding loaned buffers in the case of insuffificient resources,

   --  in order to access remaining samples.

   --  Note that in the case where the Topic associated with the DataReader

   --  is bound to a data-type that has no key definition,

   --  then there will be at most one instance in the DataReader.

   --  So the per-sample limits will apply.

   --  The act of taking a sample removes it from Data Distribution Service

   --  so it cannot be read or taken again.

   --  If the sample belongs to the most recent generation of the instance,

   --  it will also set the view_state of the sample's instance to NOT_NEW_VIEW_STATE.

   --  It will not affect the instance_state of the sample's instance.

   --  After DataReader.take completes, received_data and info_seq will be of

   --  the same length and contain the received data.

   --  If the sequences are empty (maximum size equal 0) when the take is called,

   --  the samples returned in the received_data and the corresponding

   --  info_seq are 'loaned' to the application from buffers provided by the DataReader.

   --  The application can use them as desired and has guaranteed exclusive access to them.

   --  Once the application completes its use of the samples it must 'return the loan'

   --  to the DataReader by calling the DataReader.return_loan operation.

```
   --  Note: 
```

   --   While you must call Return_Loan at some point, you do not have to do so

```
   --   before the next take call. 
```

   --  However, failure to return the loan will eventually deplete the DataReader

   --  of the buffers it needs to receive new samples and eventually samples will

   --  start to be lost. The total number of buffers available to the DataReader

   --  is specified by the ResourceLimitsQosPolicy and the DataReaderResourceLimitsQosPolicy.

   --  If the sequences are not empty (maximum size not equal 0) when the take is called,

   --  samples are copied to received_data and info_seq. The application will not

```
   --  need to call return_loan. 
```

   --  The order of the samples returned to the caller depends on the PresentationQosPolicy.

   --      * If PresentationQosPolicy::access_scope is INSTANCE_PRESENTATION_QOS,

   --        the returned collection is a list where samples belonging to the

   --        same data instance are consecutive.

   --      * If PresentationQosPolicy::access_scope is TOPIC_PRESENTATION_QOS and

   --        PresentationQosPolicy::ordered_access is set to BOOLEAN_FALSE,

   --        then returned collection is a list where samples belonging to

   --        the same data instance are consecutive.

   --      * If PresentationQosPolicy::access_scope is TOPIC_PRESENTATION_QOS and

   --        PresentationQosPolicy::ordered_access is set to TRUE, then the

   --        returned collection is a list were the relative order of samples is

   --        preserved also accross different instances. Note that samples belonging

   --        to the same instance may or may not be consecutive. This is because

   --        to preserve order it may be necessary to mix samples from different instances.

   --      * If PresentationQosPolicy::access_scope is GROUP_PRESENTATION_QOS and

   --           PresentationQosPolicy::ordered_access is set to FALSE, then returned

   --        collection is a list where samples belonging to the same data instance

   --        are consecutive. [Not supported (optional)]

   --      * If PresentationQosPolicy::access_scope is GROUP_PRESENTATION_QOS and

   --           PresentationQosPolicy::ordered_access is set to TRUE,

   --        then the returned collection contains at most one sample.

   --        The difference in this case is due to the fact that is required that

   --        the application is able to read samples belonging to different DataReader

   --        objects in a specific order. [Not supported (optional)]

   --  In any case, the relative order between the samples of one instance is consistent

   --  with the DESTINATION_ORDER policy:

   --    * If DestinationOrderQosPolicy::kind is BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS,

   --      samples belonging to the same instances will appear in the relative order

   --     in which there were received (FIFO, earlier samples ahead of the later samples).

   --    * If DestinationOrderQosPolicy::kind is BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS,

   --      samples belonging to the same instances will appear in the relative order

   --      implied by the source_timestamp (FIFO, smaller values of source_timestamp

   --      ahead of the larger values).

   --  If the DataReader has no samples that meet the constraints, the function

   --  will fail with exception NO_DATA.

   --  In addition to the collection of samples, the read and take operations also

   --   use a collection of SampleInfo structures.

   --  SEQUENCES USAGE IN TAKE AND READ

   --  The initial (input) properties of the received_data and info_seq collections

   --  will determine the precise behavior of the read or take operation.

   --  For the purposes of this description, the collections are modeled as having

```
   --  these properties: 
```

   --      * whether the collection container owns the memory of the elements

   --        within (owns, see Seq_has_ownership)

   --      * the current-length (len, see Seq_get_length)

   --      * the maximum length (max_len, see Seq_get_maximum)

```
   -- 
```

   --  The initial values of the owns, len and max_len properties for the received_data

   --  and info_seq collections govern the behavior of the read and take operations

   --  as specified by the following rules :

   --   1. The values of owns, len and max_len properties for the two collections must be identical.

   --      Otherwise read/take will fail with PRECONDITION_NOT_MET.

   --   2. On successful output, the values of owns, len and max_len

   --      will be the same for both collections.

   --   3. If the initial max_len==0, then the received_data and info_seq

   --      collections will be filled with elements that are loaned by the DataReader.

   --      On output, owns will be FALSE, len will be set to the number of values returned,

   --      and max_len will be set to a value verifying max_len >= len.

   --      The use of this variant allows for zero-copy access to the data and

   --      the application will need to return the loan to the DataWriter using return_loan.

   --   4. If the initial max_len>0 and owns==FALSE, then the read or take operation

   --      will fail with exception PRECONDITION_NOT_MET.

   --      This avoids the potential hard-to-detect memory leaks caused by an

   --      application forgetting to return the loan.

   --   5. If initial max_len>0 and owns==TRUE, then the read or take operation will copy

   --      the received_data values and SampleInfo values into the elements already

   --      inside the collections. On output, owns will be TRUE, len will be set to

   --      the number of values copied and max_len will remain unchanged.

   --      The use of this variant forces a copy but the application can control

   --      where the copy is placed and the application will not need to return the loan.

   --      The number of samples copied depends on the relative values of max_len and max_samples:

   --    * If max_samples == LENGTH_UNLIMITED, then at most max_len values will be copied.

   --      The use of this variant lets the application limit the number of samples

   --      returned to what the sequence can accommodate.

   --    * If max_samples <= max_len, then at most max_samples values will be copied.

   --      The use of this variant lets the application limit the number of samples

   --      returned to fewer that what the sequence can accommodate.

   --    * If max_samples > max_len, then the read or take operation will fail with

   --      exception PRECONDITION_NOT_MET. This avoids the potential confusion where

   --      the application expects to be able to access up to max_samples, but that

   --      number can never be returned, even if they are available in the DataReader,

   --      because the output sequence cannot accommodate them.

   --  As described above, upon completion, the received_data and info_seq collections

   --  may contain elements loaned from the DataReader.

   --  If this is the case, the application will need to use return_loan to return

   --  the loan once it is no longer using the received_data in the collection.

   --  When return_loan completes, the collection will have owns=FALSE and max_len=0.

   --  The application can determine whether it is necessary to return the loan or not

   --  based on how the state of the collections when the read/take operation was called

   --  or by accessing the owns property. However, in many cases it may be simpler to

   --  always call return_loan, as this operation is harmless

   --  (i.e., it leaves all elements unchanged) if the collection does not have a loan.

   --  To avoid potential memory leaks, the implementation of the data and SampleInfo

   --  collections should disallow changing the length of a collection for which owns==FALSE.

   --  Furthermore, deleting a collection for which owns==FALSE should be considered an error.

   --  On output, the collection of data values and the collection of SampleInfo structures

   --  are of the same length and are in a one-to-one correspondence.

   --  Each SampleInfo provides information, such as the source_timestamp,

   --  the sample_state, view_state, and instance_state, etc., about the corresponding sample.

```
   -- 
```

   --  Some elements in the returned collection may not have valid data.

   --  If the instance_state in the SampleInfo is NOT_ALIVE_DISPOSED_INSTANCE_STATE

   --  or NOT_ALIVE_NO_WRITERS_INSTANCE_STATE, then the last sample for that instance

   --  in the collection (that is, the one whose SampleInfo has sample_rank==0)

```
   --  does not contain valid data. 
```

   --  Samples that contain no data do not count towards the limits imposed by the

   --  ResourceLimitsQosPolicy. The act of reading/taking a sample sets its

   --  sample_state to READ_SAMPLE_STATE.

   --  If the sample belongs to the most recent generation of the instance,

   --  it will also set the view_state of the instance to NOT_NEW_VIEW_STATE.

   --  It will not affect the instance_state of the instance.

   --  This operation must be provided on the specialized class that is generated for

   --  the particular application data-type that is being read. If the DataReader has

   --  no samples that meet the constraints, the operations fails with exception NO_DATA.

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

   procedure Read_W_ConditionTo API doc
To body

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

      Received_Data : not null access PublicationBuiltinTopicData_Seq.SequenceTo API doc
To spec;

      Info_Seq      : not null access Standard.DDS.SampleInfo_Seq.SequenceTo API doc
To spec;

      Max_Samples   : in Standard.DDS.LongTo API doc
To spec := Standard.DDS.LENGTH_UNLIMITEDTo API doc
To spec;

      Condition     : access Standard.DDS.ReadCondition.RefTo API doc
To spec'Class);

```
   --  <internal> 
```

   --  Accesses via read the samples that match the criteria specified in the ReadCondition.

   --  This operation is especially useful in combination with QueryCondition to

   --  filter data samples based on the content.

   --  The specified ReadCondition must be attached to the DataReader;

   --  otherwise the operation will fail with exception PRECONDITION_NOT_MET.

   --  In case the ReadCondition is a plain ReadCondition and not the

   --  specialized QueryCondition, the operation is equivalent to calling read

   --  and passing as sample_states, view_states and instance_states the value of

   --  the corresponding attributes in the read_condition.

   --  Using this operation, the application can avoid repeating the same parameters

   --  specified when creating the ReadCondition.

   --  The samples are accessed with the same semantics as read.

   --  If the DataReader has no samples that meet the constraints,

   --  the operation will fail with exception RETCODE_NO_DATA.

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

   procedure Take_W_ConditionTo API doc
To body

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

      Received_Data : not null access PublicationBuiltinTopicData_Seq.SequenceTo API doc
To spec;

      Info_Seq      : not null access Standard.DDS.SampleInfo_Seq.SequenceTo API doc
To spec;

      Max_Samples   : in Standard.DDS.LongTo API doc
To spec := Standard.DDS.LENGTH_UNLIMITEDTo API doc
To spec;

      Condition     : access Standard.DDS.ReadCondition.RefTo API doc
To spec'Class);

```
   --  <internal> 
```

   --  Analogous to read_w_condition except it accesses samples via the take operation.

   --  This operation is analogous to read_w_condition except that it accesses

```
   --  samples via the take operation. 
```

   --  The specified ReadCondition must be attached to the DataReader;

   --  otherwise the operation will fail with exception PRECONDITION_NOT_MET.

   --  The samples are accessed with the same semantics as take.

   --  This operation is especially useful in combination with QueryCondition

   --  to filter data samples based on the content.

   --  If the DataReader has no samples that meet the constraints,

   --  the function will fail with exception NO_DATA.

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

   procedure Read_Next_SampleTo API doc
To body

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

      Received_Data : not null PublicationBuiltinTopicData_AccessTo API doc
To spec;

      Sample_Info   : not null access Standard.DDS.SampleInfoTo API doc
To spec);

```
   --  <internal> 
```

   --  Copies the next not-previously-accessed data value from the DataReader.

   --  This operation copies the next not-previously-accessed data value from the DataReader.

   --  This operation also copies the corresponding SampleInfo. The implied order among

   --  the samples stored in the DataReader is the same as for the read operation.

   --  The read_next_sample operation is semantically equivalent to the read operation,

   --  where the input data sequences has max_len=1, the sample_states=NOT_READ,

   --  the view_states=ANY_VIEW_STATE, and the instance_states=ANY_INSTANCE_STATE.

   --  The read_next_sample operation provides a simplified API to 'read' samples,

   --  avoiding the need for the application to manage sequences and specify states.

   --  If there is no unread data in the DataReader, the operation will fail with

   --  exception NO_DATA and nothing is copied.

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

   procedure Take_Next_SampleTo API doc
To body

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

      Received_Data : not null PublicationBuiltinTopicData_AccessTo API doc
To spec;

      Sample_Info   : not null access Standard.DDS.SampleInfoTo API doc
To spec);

```
   --  <internal> 
```

   --  Copies the next not-previously-accessed data value from the DataReader.

   --  This operation copies the next not-previously-accessed data value from the DataReader

   --  and 'removes' it from the DataReader so that it is no longer accessible.

   --  This operation also copies the corresponding SampleInfo.

   --  This operation is analogous to the read_next_sample except for the fact

   --  that the sample is removed from the DataReader.

   --  The take_next_sample operation is semantically equivalent to the take operation,

   --  where the input data sequences has max_len=1, the sample_states=NOT_READ,

   --  the view_states=ANY_VIEW_STATE, and the instance_states=ANY_INSTANCE_STATE.

   --  The read_next_sample operation provides a simplified API to 'take' samples,

   --  avoiding the need for the application to manage sequences and specify states.

   --  If tere is no unread data in the DataReader, the operation will fail

   --  with exception NO_DATA and nothing is copied.

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

   procedure Read_InstanceTo API doc
To body

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

      Received_Data   : not null access PublicationBuiltinTopicData_Seq.SequenceTo API doc
To spec;

      Info_Seq        : not null access Standard.DDS.SampleInfo_Seq.SequenceTo API doc
To spec;

      Max_Samples     : in Standard.DDS.LongTo API doc
To spec := Standard.DDS.LENGTH_UNLIMITEDTo API doc
To spec;

      A_Handle        : access constant Standard.DDS.InstanceHandle_TTo API doc
To spec;

      Sample_States   : in Standard.DDS.SampleStateMaskTo API doc
To spec := Standard.DDS.ANY_SAMPLE_STATETo API doc
To spec;

      View_States     : in Standard.DDS.ViewStateMaskTo API doc
To spec := Standard.DDS.ANY_VIEW_STATETo API doc
To spec;

      Instance_States : in Standard.DDS.InstanceStateMaskTo API doc
To spec := Standard.DDS.ANY_INSTANCE_STATETo API doc
To spec);

```
   --  <internal> 
```

   --  Access a collection of data samples from the DataReader.

   --  This operation accesses a collection of data values from the DataReader.

   --  The behavior is identical to read, except that all samples returned belong

   --  to the single specified instance whose handle is a_handle.

   --  Upon successful completion, the data collection will contain samples all

   --  belonging to the same instance. The corresponding SampleInfo verifies

   --  SampleInfo::instance_handle == a_handle.

   --  The read_instance operation is semantically equivalent to the read operation,

   --  except in building the collection, the DataReader will check that the sample

   --  belongs to the specified instance and otherwise it will not place the sample

```
   --  in the returned collection. 
```

   --  The behavior of the read_instance operation follows the same rules as the

   --  read operation regarding the pre-conditions and post-conditions for the received_data

   --  and sample_info. Similar to the read, the read_instance operation may 'loan' elements

   --  to the output collections, which must then be returned by means of return_loan.

   --  Similar to the read, this operation must be provided on the specialized class that

   --  is generated for the particular application data-type that is being taken.

   --  If the DataReader has no samples that meet the constraints,

   --  the function will fail with RETCODE_NO_DATA.

   --  This operation may fail with RETCODE_BAD_PARAMETER if the InstanceHandle_t

   --  a_handle does not correspond to an existing data-object known to the DataReader.

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

   procedure Take_InstanceTo API doc
To body

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

      Received_Data   : not null access PublicationBuiltinTopicData_Seq.SequenceTo API doc
To spec;

      Info_Seq        : not null access Standard.DDS.SampleInfo_Seq.SequenceTo API doc
To spec;

      Max_Samples     : in Standard.DDS.LongTo API doc
To spec := Standard.DDS.LENGTH_UNLIMITEDTo API doc
To spec;

      A_Handle        : access constant Standard.DDS.InstanceHandle_TTo API doc
To spec;

      Sample_States   : in Standard.DDS.SampleStateMaskTo API doc
To spec := Standard.DDS.ANY_SAMPLE_STATETo API doc
To spec;

      View_States     : in Standard.DDS.ViewStateMaskTo API doc
To spec := Standard.DDS.ANY_VIEW_STATETo API doc
To spec;

      Instance_States : in Standard.DDS.InstanceStateMaskTo API doc
To spec := Standard.DDS.ANY_INSTANCE_STATETo API doc
To spec);

```
   --  <internal> 
```

   --  Access a collection of data samples from the DataReader.

   --  This operation accesses a collection of data values from the DataReader.

   --  The behavior is identical to take, except for that all samples returned belong

   --  to the single specified instance whose handle is a_handle.

   --  The semantics are the same for the take operation, except in building the collection,

   --  the DataReader will check that the sample belongs to the specified instance,

   --  and otherwise it will not place the sample in the returned collection.

   --  The behavior of the take_instance operation follows the same rules as the

   --  read operation regarding the pre-conditions and post-conditions for the

   --  received_data and sample_info. Similar to the read, the take_instance operation may

   --  'loan' elements to the output collections, which must then be returned by means of return_loan.

   --  Similar to the read, this operation must be provided on the specialized class

   --  that is generated for the particular application data-type that is being taken.

   --  If the DataReader has no samples that meet the constraints, the function fails with exception NO_DATA.

   --  This operation may fail with exception BAD_PARAMETER if the InstanceHandle_t

   --  a_handle does not correspond to an existing data-object known to the DataReader.

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

   procedure Read_Next_InstanceTo API doc
To body

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

      Received_Data   : not null access PublicationBuiltinTopicData_Seq.SequenceTo API doc
To spec;

      Info_Seq        : not null access Standard.DDS.SampleInfo_Seq.SequenceTo API doc
To spec;

      Max_Samples     : in Standard.DDS.LongTo API doc
To spec := Standard.DDS.LENGTH_UNLIMITEDTo API doc
To spec;

      Previous_Handle : access constant Standard.DDS.InstanceHandle_TTo API doc
To spec;

      Sample_States   : in Standard.DDS.SampleStateMaskTo API doc
To spec := Standard.DDS.ANY_SAMPLE_STATETo API doc
To spec;

      View_States     : in Standard.DDS.ViewStateMaskTo API doc
To spec := Standard.DDS.ANY_VIEW_STATETo API doc
To spec;

      Instance_States : in Standard.DDS.InstanceStateMaskTo API doc
To spec := Standard.DDS.ANY_INSTANCE_STATETo API doc
To spec);

```
   --  <internal> 
```

   --  Access a collection of data samples from the DataReader.

   --  This operation accesses a collection of data values from the DataReader

   --  where all the samples belong to a single instance. The behavior is similar to

   --  read_instance, except that the actual instance is not directly specified.

   --  Rather, the samples will all belong to the 'next' instance with instance_handle

   --  'greater' than the specified 'previous_handle' that has available samples.

   --  This operation implies the existence of a total order 'greater-than' relationship

   --  between the instance handles. The specifics of this relationship are not all

   --  important and are implementation specific. The important thing is that,

   --  according to the middleware, all instances are ordered relative to each other.

   --  This ordering is between the instance handles; It should not depend on the state

   --  of the instance (e.g. whether it has data or not) and must be defined even for

   --  instance handles that do not correspond to instances currently managed by the DataReader.

   --  For the purposes of the ordering, it should be 'as if' each instance handle was

```
   --  represented as unique integer. 
```

   --  The behavior of read_next_instance is 'as if' the DataReader invoked read_instance,

   --  passing the smallest instance_handle among all the ones that:

   --   (a) are greater than previous_handle, and

   --   (b) have available samples (i.e. samples that meet the constraints imposed by the specified states).

   --  The special value HANDLE_NIL is guaranteed to be 'less than' any valid instance_handle.

   --  So the use of the parameter value previous_handle == HANDLE_NIL will

   --   return the samples for the instance which has the smallest instance_handle

   --  among all the instances that contain available samples.

   --  The operation read_next_instance is intended to be used in an

   --  application-driven iteration, where the application starts by passing

   --  previous_handle == HANDLE_NIL, examines the samples returned, and then uses

   --  the instance_handle returned in the SampleInfo as the value of the previous_handle

   --  argument to the next call to read_next_instance. The iteration continues

   --  until read_next_instance fails with the value exception NO_DATA.

   --  Note that it is possible to call the read_next_instance operation with a

   --  previous_handle that does not correspond to an instance currently managed by

   --  the DataReader. This is because as stated earlier the 'greater-than' relationship

   --  is defined even for handles not managed by the DataReader.

   --  One practical situation where this may occur is when an application is iterating

   --  though all the instances, takes all the samples of a NOT_ALIVE_NO_WRITERS_INSTANCE_STATE

   --  instance, returns the loan (at which point the instance information may be removed,

   --  and thus the handle becomes invalid), and tries to read the next instance.

   --  The behavior of the read_next_instance operation follows the same rules as

   --  the read operation regarding the pre-conditions and post-conditions for the

   --  received_data and sample_info. Similar to the read, the read_instance operation may

   --  'loan' elements to the output collections, which must then be returned by means of return_loan.

   --  Similar to the read, this operation must be provided on the specialized class

   --  that is generated for the particular application data-type that is being taken.

   --  If the DataReader has no samples that meet the constraints, the function

   --  will fail with exception NO_DATA.

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

   procedure Take_Next_InstanceTo API doc
To body

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

      Received_Data   : not null access PublicationBuiltinTopicData_Seq.SequenceTo API doc
To spec;

      Info_Seq        : not null access Standard.DDS.SampleInfo_Seq.SequenceTo API doc
To spec;

      Max_Samples     : in Standard.DDS.LongTo API doc
To spec := Standard.DDS.LENGTH_UNLIMITEDTo API doc
To spec;

      Previous_Handle : access constant Standard.DDS.InstanceHandle_TTo API doc
To spec;

      Sample_States   : in Standard.DDS.SampleStateMaskTo API doc
To spec := Standard.DDS.ANY_SAMPLE_STATETo API doc
To spec;

      View_States     : in Standard.DDS.ViewStateMaskTo API doc
To spec := Standard.DDS.ANY_VIEW_STATETo API doc
To spec;

      Instance_States : in Standard.DDS.InstanceStateMaskTo API doc
To spec := Standard.DDS.ANY_INSTANCE_STATETo API doc
To spec);

```
   --  <internal> 
```

   --  Access a collection of data samples from the DataReader.

   --  This operation accesses a collection of data values from the DataReader and

   --  'removes' them from the DataReader.

   --  This operation has the same behavior as read_next_instance, except that the

   --  samples are 'taken' from the DataReader such that they are no longer accessible

   --  via subsequent 'read' or 'take' operations.

   --  Similar to the operation read_next_instance, it is possible to call take_next_instance

   --  with a previous_handle that does not correspond to an instance currently managed by the DataReader.

   --  The behavior of the take_next_instance operation follows the same rules as the

   --  read operation regarding the pre-conditions and post-conditions for the received_data

   --  and sample_info. Similar to the read, the take_next_instance operation may 'loan'

   --  elements to the output collections, which must then be returned by means of return_loan.

   --  Similar to the read, this operation must be provided on the specialized class that

   --  is generated for the particular application data-type that is being taken.

   --  If the DataReader has no samples that meet the constraints,

   --  the function will fail with exception NO_DATA.

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

   procedure Read_Next_Instance_W_ConditionTo API doc
To body

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

      Received_Data   : not null access PublicationBuiltinTopicData_Seq.SequenceTo API doc
To spec;

      Info_Seq        : not null access Standard.DDS.SampleInfo_Seq.SequenceTo API doc
To spec;

      Max_Samples     : in Standard.DDS.LongTo API doc
To spec := Standard.DDS.LENGTH_UNLIMITEDTo API doc
To spec;

      Previous_Handle : access constant Standard.DDS.InstanceHandle_TTo API doc
To spec;

      Condition       : Standard.DDS.ReadCondition.Ref_AccessTo API doc
To spec);

```
   --  <internal> 
```

   --  Accesses via read_next_instance the samples that match the criteria

```
   --  specified in the ReadCondition. 
```

   --  This operation access a collection of data values from the DataReader.

   --  The behavior is identical to read_next_instance, except that all samples returned satisfy

   --  the specified condition. In other words, on success, all returned samples

   --  belong to the same instance, and the instance is the instance with 'smallest'

   --  instance_handle among the ones that verify:

   --   (a) instance_handle >= previous_handle, and

   --   (b) have samples for which the specified ReadCondition evaluates to TRUE.

   --  Similar to the operation read_next_instance, it is possible to call

   --  read_next_instance_w_condition with a previous_handle that does not correspond

   --  to an instance currently managed by the DataReader.

   --  The behavior of the read_next_instance_w_condition operation follows the same

   --  rules as the read operation regarding the pre-conditions and post-conditions for

   --  the received_data and sample_info. Similar to the read, the

   --  read_next_instance_w_condition operation may 'loan' elements to the output collections,

   --  which must then be returned by means of return_loan.

   --  Similar to the read, this operation must be provided on the specialized class that

   --  is generated for the particular application data-type that is being taken.

   --  If the DataReader has no samples that meet the constraints,

   --  the function will fail with exception NO_DATA.

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

   procedure Take_Next_Instance_W_ConditionTo API doc
To body

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

      Received_Data   : not null access PublicationBuiltinTopicData_Seq.SequenceTo API doc
To spec;

      Info_Seq        : not null access Standard.DDS.SampleInfo_Seq.SequenceTo API doc
To spec;

      Max_Samples     : in Standard.DDS.LongTo API doc
To spec := Standard.DDS.LENGTH_UNLIMITEDTo API doc
To spec;

      Previous_Handle : access constant Standard.DDS.InstanceHandle_TTo API doc
To spec;

      Condition       : Standard.DDS.ReadCondition.Ref_AccessTo API doc
To spec);

```
   --  <internal> 
```

   --  Accesses via take_next_instance the samples that match the criteria specified

```
   --  in the ReadCondition. 
```

   --  This operation access a collection of data values from the DataReader and

   --  'removes' them from the DataReader.

   --  The operation has the same behavior as read_next_instance_w_condition, except

   --  that the samples are 'taken' from the DataReader such that they are no longer

   --  accessible via subsequent 'read' or 'take' operations.

   --  Similar to the operation read_next_instance, it is possible to call

   --  take_next_instance_w_condition with a previous_handle that does not correspond

   --  to an instance currently managed by the DataReader.

   --  The behavior of the take_next_instance_w_condition operation follows the same

   --  rules as the read operation regarding the pre-conditions and post-conditions

   --  for the received_data and sample_info. Similar to the read,

   --  the take_next_instance_w_condition operation may 'loan' elements to the output

   --  collections, which must then be returned by means of return_loan.

   --  Similar to the read, this operation must be provided on the specialized class

   --  that is generated for the particular application data-type that is being taken.

   --  If the DataReader has no samples that meet the constraints,

   --  the function will fail with exception NO_DATA.

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

   procedure Return_LoanTo API doc
To body

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

      Received_Data : not null access PublicationBuiltinTopicData_Seq.SequenceTo API doc
To spec;

      Info_Seq      : not null access Standard.DDS.SampleInfo_Seq.SequenceTo API doc
To spec);

```
   --  <internal> 
```

   --  Indicates to the DataReader that the application is done accessing the collection

   --  of received_data and info_seq obtained by some earlier invocation of

```
   --  read or take on the DataReader. 
```

   --  This operation indicates to the DataReader that the application is done accessing

   --  the collection of received_data and info_seq obtained by some earlier

   --  invocation of read or take on the DataReader.

   --  The received_data and info_seq must belong to a single related "pair"; that is,

   --  they should correspond to a pair returned from a single call to read or take.

   --  The received_data and info_seq must also have been obtained from the same DataReader

   --  to which they are returned. If either of these conditions is not met, the operation

   --  will fail with exception PRECONDITION_NOT_MET.

   --  The operation return_loan allows implementations of the read and take operations

   --  to "loan" buffers from the DataReader to the application and in this manner provide

   --  "zerocopy" access to the data. During the loan, the DataReader will guarantee

   --  that the data and sample-information are not modified.

   --  It is not necessary for an application to return the loans immediately after

   --  the read or take calls. However, as these buffers correspond to internal resources

   --  inside the DataReader, the application should not retain them indefinitely.

   --  The use of return_loan is only necessary if the read or take calls "loaned"

   --  buffers to the application. This only occurs if the received_data and info_Seq

   --  collections had max_len=0 at the time read or take was called.

   --  The application may also examine the "owns" property of the collection to determine

   --  where there is an outstanding loan. However, calling return_loan on a collection

   --  that does not have a loan is safe and has no side effects.

   --  If the collections had a loan, upon completion of return_loan,

   --  the collections will have max_len=0.

   --  Similar to read, this operation must be provided on the specialized class that

   --  is generated for the particular application data-type that is being taken.

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

   procedure Get_Key_ValueTo API doc
To body

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

      Key_Holder : not null PublicationBuiltinTopicData_AccessTo API doc
To spec;

      Handle     : access constant Standard.DDS.InstanceHandle_TTo API doc
To spec);

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

   --  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 DDS_DataReader.

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

   function Lookup_InstanceTo API doc
To body

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

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

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

   --  the Service is unable to provide an instance handle,

   --  the Service will return the special value HANDLE_NIL

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

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

```
   -- 
```

   --  Internal Routines not to be used by the application

```
   -- 
```

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

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

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

```
 
```

   procedure DestroyTypedITo API doc
To body

     (Reader : in out Standard.DDS.DataReader.Ref_AccessTo API doc
To spec);

```
 
```

end DDS.PublicationBuiltinTopicData_DataReader;

RTI Connext Ada API