type Ref is new DDS.DataReader_Impl.Ref with null record;
type Ref_Access is access all Ref;
type Element_Type is record Data : Data_Type_Access; Sample_Info : SampleInfo_Access; end record;
type Cursor is new DDS.Natural;
function I_Has_Element
( | Self | : Container; |
C | : Cursor) return Standard.Boolean; |
function I_Get_Element
( | Self | : Container; |
C | : Cursor) return Element_Type; |
procedure Read
( | Self | : not null access Ref; |
Received_Data | : not null access Data_Sequences.Sequence; | |
Info_Seq | : not null access DDS.SampleInfo_Seq.Sequence; | |
Max_Samples | : in DDS.Long := DDS.LENGTH_UNLIMITED; | |
Sample_States | : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE; | |
View_States | : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE; | |
Instance_States | : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE); |
procedure Read
( | Self | : not null access Ref; |
Received_Data | : in out Data_Sequences.Sequence; | |
Info_Seq | : in out DDS.SampleInfo_Seq.Sequence; | |
Max_Samples | : in DDS.Long := DDS.LENGTH_UNLIMITED; | |
Sample_States | : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE; | |
View_States | : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE; | |
Instance_States | : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE); |
function Read
( | Self | : not null access Ref; |
Max_Samples | : in DDS.Long := DDS.LENGTH_UNLIMITED; | |
Sample_States | : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE; | |
View_States | : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE; | |
Instance_States | : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE) return Container'Class; |
This operation offers the same functionality and API as FooDataReader.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 FooDataReader.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.
Once the application completes its use of the samples, it must 'return the loan' to the DDS.DataReader by calling the FooDataReader.return_loan operation.
Important: When you loan data from the middleware, you must not keep any pointers to any part of the data samples or the DDS.SampleInfo objects after the call to FooDataReader.return_loan. Returning the loan places the objects back into a pool, allowing the middleware to overwrite them with new data.
Note: While you must call FooDataReader.return_loan at some point, you do not have to do so before the next FooDataReader.take call. However, failure to return the loan will eventually deplete the DDS.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 DDS.DataReader is specified by the DDS.ResourceLimitsQosPolicy and the DDS.DataReaderResourceLimitsQosPolicy.
Important: If the samples "returned" by this procedure are loaned from RTI Connext (see FooDataReader.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.
self: <<in>> Cannot be NULL
received_data: <<inout>> User data type-specific FooSeq object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
info_seq: <<inout>> A DDS.SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL DDS.SampleInfoSeq. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
max_samples: <<in>> The maximum number of samples to be returned. If the special value DDS.LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for FooDataReader.take().
sample_states: <<in>> Data samples matching one of these sample_states are returned. See the valid values for this parameter here: DDS.SampleStateKind.
view_states: <<in>> Data samples matching one of these view_state are returned. See the valid values for this parameter here: DDS.ViewStateKind.
instance_states: <<in>> Data samples matching ones of these instance_state are returned. See the valid values for this parameter here: DDS.InstanceStateKind.
Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_PRECONDITION_NOT_MET, DDS.RETCODE_NO_DATA or DDS.RETCODE_NOT_ENABLED.
See also: FooDataReader.take
See also: FooDataReader.read_w_condition,
See also: FooDataReader.take_w_condition
See also: DDS.LENGTH_UNLIMITED
procedure Take
( | Self | : not null access Ref; |
Received_Data | : not null access Data_Sequences.Sequence; | |
Info_Seq | : not null access DDS.SampleInfo_Seq.Sequence; | |
Max_Samples | : in DDS.Long := DDS.LENGTH_UNLIMITED; | |
Sample_States | : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE; | |
View_States | : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE; | |
Instance_States | : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE); |
procedure Take
( | Self | : not null access Ref; |
Received_Data | : out Data_Sequences.Sequence; | |
Info_Seq | : out DDS.SampleInfo_Seq.Sequence; | |
Max_Samples | : in DDS.Long := DDS.LENGTH_UNLIMITED; | |
Sample_States | : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE; | |
View_States | : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE; | |
Instance_States | : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE); |
function Take
( | Self | : not null access Ref; |
Max_Samples | : in DDS.Long := DDS.LENGTH_UNLIMITED; | |
Sample_States | : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE; | |
View_States | : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE; | |
Instance_States | : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE) return Container'Class; |
The operation will return the list of samples received by the DDS.DataReader since the last FooDataReader.take operation that matches the specified DDS.SampleStateMask, DDS.ViewStateMask and DDS.InstanceStateMask.
This operation may fail with DDS.RETCODE_ERROR if the DDS.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 DDS.HistoryQosPolicy, DDS.ResourceLimitsQosPolicy, DDS.DataReaderResourceLimitsQosPolicy and the characteristics of the data-type that is associated with the DDS.DataReader:
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 DDS.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 insufficient resources, in order to access remaining samples.
Note that in the case where the DDS.Topic associated with the DDS.DataReader is bound to a data-type that has no key definition, then there will be at most one instance in the DDS.DataReader. So the per-sample limits will apply.
The act of taking a sample removes it from RTI Connext 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 DDS.NOT_NEW_VIEW_STATE. It will not affect the instance_state of the sample's instance.
After FooDataReader.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 equals 0) when the FooDataReader.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 DDS.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 DDS.DataReader by calling the FooDataReader.return_loan operation. To copy samples from the reader instead of taking a loan, you can use any of the read or take operations that receive an iterator to a container in which to copy the samples:
The order of the samples returned to the caller depends on the DDS.PresentationQosPolicy.
In any case, the relative order between the samples of one instance is consistent with the DDSDestinationOrderQosModule policy:
If the DDS.DataReader has no samples that meet the constraints, the procedure will fail with DDS.RETCODE_NO_DATA.
In addition to the collection of samples, the read and take operations also use a collection of DDS.SampleInfo structures.
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:
As described above, upon completion, the received_data and info_seq collections may contain elements loaned from the DDS.DataReader. If this is the case, the application will need to use FooDataReader.return_loan to return the loan once it is no longer using the received_data in the collection. When FooDataReader.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 FooDataReader.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 Foo and DDS.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 Foo values and the collection of DDS.SampleInfo structures are of the same length and are in a one-to-one correspondence. Each DDS.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 DDS.SampleInfo is DDS.NOT_ALIVE_DISPOSED_INSTANCE_STATE or DDS.NOT_ALIVE_NO_WRITERS_INSTANCE_STATE, then the last sample for that instance in the collection (that is, the one whose DDS.SampleInfo has sample_rank==0) does not contain valid data.
Samples that contain no data do not count towards the limits imposed by the DDS.ResourceLimitsQosPolicy. The act of reading/taking a sample sets 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 DDS.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 (Foo).
If the DDS.DataReader has no samples that meet the constraints, the operations fails with DDS.RETCODE_NO_DATA.
received_data: <<inout>> User data type-specific FooSeq object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
self: <<in>> Cannot be NULL
info_seq: <<inout>> A DDS.SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL DDS.SampleInfoSeq. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
max_samples: <<in>> The maximum number of samples to be returned. If the special value DDS.LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described above.
sample_states: <<in>> Data samples matching one of these sample_states are returned. See the valid values for this parameter here: DDS.SampleStateKind.
view_states: <<in>> Data samples matching one of these view_state are returned. See the valid values for this parameter here: DDS.ViewStateKind.
instance_states: <<in>> Data samples matching one of these instance_state are returned. See the valid values for this parameter here: DDS.InstanceStateKind.
Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_PRECONDITION_NOT_MET, DDS.RETCODE_NO_DATA or DDS.RETCODE_NOT_ENABLED.
See also: FooDataReader.read
See also: FooDataReader.read_w_condition, FooDataReader.take_w_condition
See also: DDS.LENGTH_UNLIMITED
procedure Read_W_Condition
( | Self | : not null access Ref; |
Received_Data | : not null access Data_Sequences.Sequence; | |
Info_Seq | : not null access DDS.SampleInfo_Seq.Sequence; | |
Max_Samples | : in DDS.Long := DDS.LENGTH_UNLIMITED; | |
Condition | : access DDS.ReadCondition.Ref'Class); |
procedure Read_W_Condition
( | Self | : not null access Ref; |
Received_Data | : out Data_Sequences.Sequence; | |
Info_Seq | : out DDS.SampleInfo_Seq.Sequence; | |
Max_Samples | : in DDS.Long := DDS.LENGTH_UNLIMITED; | |
Condition | : access DDS.ReadCondition.Ref'Class); |
function Read_W_Condition
( | Self | : not null access Ref; |
Max_Samples | : in DDS.Long := DDS.LENGTH_UNLIMITED; | |
Condition | : access DDS.ReadCondition.Ref'Class) return Container'Class; |
This operation is especially useful in combination with DDS.QueryCondition to filter data samples based on the content.
The specified DDS.ReadCondition must be attached to the DDS.DataReader; otherwise the operation will fail with DDS.RETCODE_PRECONDITION_NOT_MET.
In case the DDS.ReadCondition is a plain DDS.ReadCondition and not the specialized DDS.QueryCondition, the operation is equivalent to calling FooDataReader.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 DDS.ReadCondition.
The samples are accessed with the same semantics as FooDataReader.read.
If the DDS.DataReader has no samples that meet the constraints, the operation will fail with DDS.RETCODE_NO_DATA.
self: <<in>> Cannot be NULL
received_data: <<inout>> user data type-specific FooSeq object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
info_seq: <<inout>> a DDS.SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL DDS.SampleInfoSeq. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
max_samples: <<in>> The maximum number of samples to be returned. If the special value DDS.LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for FooDataReader.take().
condition: <<in>> the DDS.ReadCondition to select samples of interest. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_PRECONDITION_NOT_MET, DDS.RETCODE_NO_DATA or DDS.RETCODE_NOT_ENABLED.
See also: FooDataReader.read
See also: FooDataReader.take, FooDataReader.take_w_condition
See also: DDS.LENGTH_UNLIMITED
Ret.Received_Data
procedure Take_W_Condition
( | Self | : not null access Ref; |
Received_Data | : not null access Data_Sequences.Sequence; | |
Info_Seq | : not null access DDS.SampleInfo_Seq.Sequence; | |
Max_Samples | : in DDS.Long := DDS.LENGTH_UNLIMITED; | |
Condition | : access DDS.ReadCondition.Ref'Class); |
function Take_W_Condition
( | Self | : not null access Ref; |
Max_Samples | : in DDS.Long := DDS.LENGTH_UNLIMITED; | |
Condition | : access DDS.ReadCondition.Ref'Class) return Container'Class; |
This operation is analogous to FooDataReader.read_w_condition except that it accesses samples via the FooDataReader.take operation.
The specified DDS.ReadCondition must be attached to the DDS.DataReader; otherwise the operation will fail with DDS.RETCODE_PRECONDITION_NOT_MET.
The samples are accessed with the same semantics as FooDataReader.take.
This operation is especially useful in combination with DDS.QueryCondition to filter data samples based on the content.
If the DDS.DataReader has no samples that meet the constraints, the procedure will fail with DDS.RETCODE_NO_DATA.
self: <<in>> Cannot be NULL
received_data: <<inout>> user data type-specific FooSeq object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
info_seq: <<inout>> a DDS.SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL DDS.SampleInfoSeq. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
max_samples: <<in>> The maximum number of samples to be returned. If the special value DDS.LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for FooDataReader.take().
condition: <<in>> the DDS.ReadCondition to select samples of interest. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_PRECONDITION_NOT_MET, DDS.RETCODE_NO_DATA or DDS.RETCODE_NOT_ENABLED.
See also: FooDataReader.read_w_condition, FooDataReader.read
See also: FooDataReader.take
See also: DDS.LENGTH_UNLIMITED
procedure Read_Next_Sample
( | Self | : not null access Ref; |
Received_Data | : out Data_Type; | |
Sample_Info | : not null access DDS.SampleInfo); |
procedure Read_Next_Sample
( | Self | : not null access Ref; |
Received_Data | : not null Data_Type_Access; | |
Sample_Info | : not null access DDS.SampleInfo); |
This operation copies the next not-previously-accessed data value from the DDS.DataReader. This operation also copies the corresponding DDS.SampleInfo. The implied order among the samples stored in the DDS.DataReader is the same as for the FooDataReader.read operation.
The FooDataReader.read_next_sample operation is semantically equivalent to the FooDataReader.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 FooDataReader.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 DDS.DataReader, the operation will fail with DDS.RETCODE_NO_DATA and nothing is copied.
self: <<in>> Cannot be NULL
received_data: <<inout>> user data type-specific Foo object where the next received data sample will be returned. The received_data must have been fully allocated. Otherwise, this operation may fail. Must be a valid non-NULL Foo. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
sample_info: <<inout>> a DDS.SampleInfo object where the next received sample info will be returned. Must be a valid non-NULL DDS.SampleInfo. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_NO_DATA or DDS.RETCODE_NOT_ENABLED.
See also: FooDataReader.read
procedure Take_Next_Sample
( | Self | : not null access Ref; |
Received_Data | : not null Data_Type_Access; | |
Sample_Info | : not null access DDS.SampleInfo); |
procedure Take_Next_Sample
( | Self | : not null access Ref; |
Received_Data | : out Data_Type; | |
Sample_Info | : not null access DDS.SampleInfo); |
This operation copies the next not-previously-accessed data value from the DDS.DataReader and 'removes' it from the DDS.DataReader so that it is no longer accessible. This operation also copies the corresponding DDS.SampleInfo. This operation is analogous to the FooDataReader.read_next_sample except for the fact that the sample is removed from the DDS.DataReader.
The FooDataReader.take_next_sample operation is semantically equivalent to the FooDataReader.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 FooDataReader.take_next_sample operation provides a simplified API to 'take' samples, avoiding the need for the application to manage sequences and specify states.
If there is no unread data in the DDS.DataReader, the operation will fail with DDS.RETCODE_NO_DATA and nothing is copied.
self: <<in>> Cannot be NULL
received_data: <<inout>> user data type-specific Foo object where the next received data sample will be returned. The received_data must have been fully allocated. Otherwise, this operation may fail. Must be a valid non-NULL Foo. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
sample_info: <<inout>> a DDS.SampleInfo object where the next received sample info will be returned. Must be a valid non-NULL DDS.SampleInfo. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL. Raises: One of the DDSReturnTypesModules_std_retcodes,
DDS.RETCODE_NO_DATA or DDS.RETCODE_NOT_ENABLED.
See also: FooDataReader.take
procedure Read_Instance
( | Self | : not null access Ref; |
Received_Data | : not null access Data_Sequences.Sequence; | |
Info_Seq | : not null access DDS.SampleInfo_Seq.Sequence; | |
Max_Samples | : in DDS.Long := DDS.LENGTH_UNLIMITED; | |
A_Handle | : access constant DDS.InstanceHandle_T; | |
Sample_States | : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE; | |
View_States | : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE; | |
Instance_States | : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE); |
function Read_Instance
( | Self | : not null access Ref; |
Max_Samples | : in DDS.Long := DDS.LENGTH_UNLIMITED; | |
A_Handle | : access constant DDS.InstanceHandle_T; | |
Sample_States | : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE; | |
View_States | : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE; | |
Instance_States | : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE) return Container'Class; |
This operation accesses a collection of data values from the DDS.DataReader. The behavior is identical to FooDataReader.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 DDS.SampleInfo verifies DDS.SampleInfo.instance_handle == a_handle.
The FooDataReader.read_instance operation is semantically equivalent to the FooDataReader.read operation, except in building the collection, the DDS.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 FooDataReader.read_instance operation follows the same rules as the FooDataReader.read operation regarding the pre-conditions and post-conditions for the received_data and sample_info. Similar to the FooDataReader.read, the FooDataReader.read_instance operation may 'loan' elements to the output collections, which must then be returned by means of FooDataReader.return_loan.
Similar to the FooDataReader.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 DDS.DataReader has no samples that meet the constraints, the procedure will fail with DDS.RETCODE_NO_DATA.
This operation may fail with DDS.RETCODE_BAD_PARAMETER if the DDS.InstanceHandle_t a_handle does not correspond to an existing data-object known to the DDS.DataReader.
self: <<in>> Cannot be NULL
received_data: <<inout>> user data type-specific FooSeq object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
info_seq: <<inout>> a DDS.SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL DDS.SampleInfoSeq. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
max_samples: <<in>> The maximum number of samples to be returned. If the special value DDS.LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for FooDataReader.take().
a_handle: <<in>> The specified instance to return samples for. Must be a valid non-NULL DDS.InstanceHandle_t. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL The procedure will fail with DDS.RETCODE_BAD_PARAMETER if the handle does not correspond to an existing data-object known to the DDS.DataReader.
sample_states: <<in>> data samples matching ones of these sample_states are returned. See the valid values for this parameter here: DDS.SampleStateKind.
view_states: <<in>> data samples matching ones of these view_state are returned. See the valid values for this parameter here: DDS.ViewStateKind.
instance_states: <<in>> data samples matching ones of these instance_state are returned. See the valid values for this parameter here: DDS.InstanceStateKind.
Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_PRECONDITION_NOT_MET, DDS.RETCODE_NO_DATA or DDS.RETCODE_NOT_ENABLED.
See also: FooDataReader.read
See also: DDS.LENGTH_UNLIMITED
procedure Take_Instance
( | Self | : not null access Ref; |
Received_Data | : not null access Data_Sequences.Sequence; | |
Info_Seq | : not null access DDS.SampleInfo_Seq.Sequence; | |
Max_Samples | : in DDS.Long := DDS.LENGTH_UNLIMITED; | |
A_Handle | : access constant DDS.InstanceHandle_T; | |
Sample_States | : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE; | |
View_States | : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE; | |
Instance_States | : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE); |
function Take_Instance
( | Self | : not null access Ref; |
Max_Samples | : in DDS.Long := DDS.LENGTH_UNLIMITED; | |
A_Handle | : access constant DDS.InstanceHandle_T; | |
Sample_States | : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE; | |
View_States | : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE; | |
Instance_States | : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE) return Container'Class; |
This operation accesses a collection of data values from the DDS.DataReader. The behavior is identical to FooDataReader.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 FooDataReader.take operation, except in building the collection, the DDS.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 FooDataReader.take_instance operation follows the same rules as the FooDataReader.read operation regarding the pre-conditions and post-conditions for the received_data and sample_info. Similar to the FooDataReader.read, the FooDataReader.take_instance operation may 'loan' elements to the output collections, which must then be returned by means of FooDataReader.return_loan.
Similar to the FooDataReader.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 DDS.DataReader has no samples that meet the constraints, the procedure fails with DDS.RETCODE_NO_DATA.
This operation may fail with DDS.RETCODE_BAD_PARAMETER if the DDS.InstanceHandle_t a_handle does not correspond to an existing data-object known to the DDS.DataReader.
self: <<in>> Cannot be NULL
received_data: <<inout>> user data type-specific FooSeq object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
info_seq: <<inout>> a DDS.SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL DDS.SampleInfoSeq. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
max_samples: <<in>> The maximum number of samples to be returned. If the special value DDS.LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for FooDataReader.take().
a_handle: <<in>> The specified instance to return samples for. Must be a valid non-NULL DDS.InstanceHandle_t. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if the handle does not correspond to an existing data-object known to the DDS.DataReader.
sample_states: <<in>> data samples matching ones of these sample_states are returned. See the valid values for this parameter here: DDS.SampleStateKind.
view_states: <<in>> data samples matching ones of these view_state are returned. See the valid values for this parameter here: DDS.ViewStateKind.
instance_states: <<in>> data samples matching ones of these instance_state are returned. See the valid values for this parameter here: DDS.InstanceStateKind.
Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_PRECONDITION_NOT_MET, DDS.RETCODE_NO_DATA or DDS.RETCODE_NOT_ENABLED.
See also: FooDataReader.take
See also: DDS.LENGTH_UNLIMITED
procedure Read_Next_Instance
( | Self | : not null access Ref; |
Received_Data | : not null access Data_Sequences.Sequence; | |
Info_Seq | : not null access DDS.SampleInfo_Seq.Sequence; | |
Max_Samples | : in DDS.Long := DDS.LENGTH_UNLIMITED; | |
Previous_Handle | : access constant DDS.InstanceHandle_T; | |
Sample_States | : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE; | |
View_States | : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE; | |
Instance_States | : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE); |
function Read_Next_Instance
( | Self | : not null access Ref; |
Max_Samples | : in DDS.Long := DDS.LENGTH_UNLIMITED; | |
Previous_Handle | : access constant DDS.InstanceHandle_T; | |
Sample_States | : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE; | |
View_States | : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE; | |
Instance_States | : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE) return Container'Class; |
This operation accesses a collection of data values from the DDS.DataReader where all the samples belong to a single instance. The behavior is similar to FooDataReader.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 DDS.DataReader. For the purposes of the ordering, it should be 'as if' each instance handle was represented as unique integer.
The behavior of FooDataReader.read_next_instance is 'as if' the DDS.DataReader invoked FooDataReader.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 DDS_HANDLE_NIL is guaranteed to be 'less than' any valid instance_handle. So the use of the parameter value previous_handle == DDS_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 FooDataReader.read_next_instance is intended to be used in an application-driven iteration, where the application starts by passing previous_handle == DDS_HANDLE_NIL, examines the samples returned, and then uses the instance_handle returned in the DDS.SampleInfo as the value of the previous_handle argument to the next call to FooDataReader.read_next_instance. The iteration continues until FooDataReader.read_next_instance fails with the value DDS.RETCODE_NO_DATA .
Note that it is possible to call the FooDataReader.read_next_instance operation with a previous_handle that does not correspond to an instance currently managed by the DDS.DataReader. This is because as stated earlier the 'greater-than' relationship is defined even for handles not managed by the DDS.DataReader. One practical situation where this may occur is when an application is iterating though all the instances, takes all the samples of a DDS.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 FooDataReader.read_next_instance operation follows the same rules as the FooDataReader.read operation regarding the pre-conditions and post-conditions for the received_data and sample_info. Similar to the FooDataReader.read, the FooDataReader.read_instance operation may 'loan' elements to the output collections, which must then be returned by means of FooDataReader.return_loan.
Similar to the FooDataReader.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 DDS.DataReader has no samples that meet the constraints, the procedure will fail with DDS.RETCODE_NO_DATA.
self: <<in>> Cannot be NULL
received_data: <<inout>> user data type-specific FooSeq object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
info_seq: <<inout>> a DDS.SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL DDS.SampleInfoSeq. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
max_samples: <<in>> The maximum number of samples to be returned. If the special value DDS.LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for FooDataReader.take().
previous_handle: <<in>> The 'next smallest' instance with a value greater than this value that has available samples will be returned. Must be a valid non-NULL DDS.InstanceHandle_t. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
sample_states: <<in>> data samples matching ones of these sample_states are returned. See the valid values for this parameter here: DDS.SampleStateKind.
view_states: <<in>> data samples matching ones of these view_state are returned. See the valid values for this parameter here: DDS.ViewStateKind.
instance_states: <<in>> data samples matching ones of these instance_state are returned. See the valid values for this parameter here: DDS.InstanceStateKind.
Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_PRECONDITION_NOT_MET DDS.RETCODE_NO_DATA or DDS.RETCODE_NOT_ENABLED.
See also: FooDataReader.read
See also: DDS.LENGTH_UNLIMITED
procedure Take_Next_Instance
( | Self | : not null access Ref; |
Received_Data | : not null access Data_Sequences.Sequence; | |
Info_Seq | : not null access DDS.SampleInfo_Seq.Sequence; | |
Max_Samples | : in DDS.Long := DDS.LENGTH_UNLIMITED; | |
Previous_Handle | : access constant DDS.InstanceHandle_T; | |
Sample_States | : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE; | |
View_States | : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE; | |
Instance_States | : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE); |
function Take_Next_Instance
( | Self | : not null access Ref; |
Max_Samples | : in DDS.Long := DDS.LENGTH_UNLIMITED; | |
Previous_Handle | : access constant DDS.InstanceHandle_T; | |
Sample_States | : in DDS.SampleStateMask := DDS.ANY_SAMPLE_STATE; | |
View_States | : in DDS.ViewStateMask := DDS.ANY_VIEW_STATE; | |
Instance_States | : in DDS.InstanceStateMask := DDS.ANY_INSTANCE_STATE) return Container'Class; |
This operation accesses a collection of data values from the DDS.DataReader and 'removes' them from the DDS.DataReader.
This operation has the same behavior as FooDataReader.read_next_instance, except that the samples are 'taken' from the DDS.DataReader such that they are no longer accessible via subsequent 'read' or 'take' operations.
Similar to the operation FooDataReader.read_next_instance, it is possible to call FooDataReader.take_next_instance with a previous_handle that does not correspond to an instance currently managed by the DDS.DataReader.
The behavior of the FooDataReader.take_next_instance operation follows the same rules as the FooDataReader.read operation regarding the pre-conditions and post-conditions for the received_data and sample_info. Similar to the FooDataReader.read, the FooDataReader.take_next_instance operation may 'loan' elements to the output collections, which must then be returned by means of FooDataReader.return_loan.
Similar to the FooDataReader.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 DDS.DataReader has no samples that meet the constraints, the procedure will fail with DDS.RETCODE_NO_DATA.
self: <<in>> Cannot be NULL
received_data: <<inout>> user data type-specific FooSeq object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
info_seq: <<inout>> a DDS.SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL DDS.SampleInfoSeq. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
max_samples: <<in>> The maximum number of samples to be returned. If the special value DDS.LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for FooDataReader.take().
previous_handle: <<in>> The 'next smallest' instance with a value greater than this value that has available samples will be returned. Must be a valid non-NULL DDS.InstanceHandle_t. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
sample_states: <<in>> data samples matching ones of these sample_states are returned. See the valid values for this parameter here: DDS.SampleStateKind.
view_states: <<in>> data samples matching ones of these view_state are returned. See the valid values for this parameter here: DDS.ViewStateKind.
instance_states: <<in>> data samples matching ones of these instance_state are returned. See the valid values for this parameter here: DDS.InstanceStateKind.
Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_PRECONDITION_NOT_MET, DDS.RETCODE_NO_DATA or DDS.RETCODE_NOT_ENABLED.
See also: FooDataReader.take
See also: DDS.LENGTH_UNLIMITED
procedure Read_Next_Instance_W_Condition
( | Self | : not null access Ref; |
Received_Data | : not null access Data_Sequences.Sequence; | |
Info_Seq | : not null access DDS.SampleInfo_Seq.Sequence; | |
Max_Samples | : in DDS.Long := DDS.LENGTH_UNLIMITED; | |
Previous_Handle | : access constant DDS.InstanceHandle_T; | |
Condition | : DDS.ReadCondition.Ref_Access); |
function Read_Next_Instance_W_Condition
( | Self | : not null access Ref; |
Max_Samples | : in DDS.Long := DDS.LENGTH_UNLIMITED; | |
Previous_Handle | : access constant DDS.InstanceHandle_T; | |
Condition | : DDS.ReadCondition.Ref_Access) return Container'Class; |
This operation accesses a collection of data values from the DDS.DataReader. The behavior is identical to FooDataReader.read_next_instance, except that all returned samples 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 DDS.ReadCondition evaluates to TRUE.
Similar to the operation FooDataReader.read_next_instance, it is possible to call FooDataReader.read_next_instance_w_condition with a previous_handle that does not correspond to an instance currently managed by the DDS.DataReader.
The behavior of the FooDataReader.read_next_instance_w_condition operation follows the same rules as the FooDataReader.read operation regarding the pre-conditions and post-conditions for the received_data and sample_info. Similar to the FooDataReader.read, the FooDataReader.read_next_instance_w_condition operation may 'loan' elements to the output collections, which must then be returned by means of FooDataReader.return_loan.
Similar to the FooDataReader.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 DDS.DataReader has no samples that meet the constraints, the procedure will fail with DDS.RETCODE_NO_DATA.
self: <<in>> Cannot be NULL
received_data: <<inout>> user data type-specific FooSeq object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
info_seq: <<inout>> a DDS.SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL DDS.SampleInfoSeq. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
max_samples: <<in>> The maximum number of samples to be returned. If the special value DDS.LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for FooDataReader.take().
previous_handle: <<in>> The 'next smallest' instance with a value greater than this value that has available samples will be returned. Must be a valid non-NULL DDS.InstanceHandle_t. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
condition: <<in>> the DDS.ReadCondition to select samples of interest. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_PRECONDITION_NOT_MET DDS.RETCODE_NO_DATA or DDS.RETCODE_NOT_ENABLED.
See also: FooDataReader.read_next_instance
See also: DDS.LENGTH_UNLIMITED
procedure Take_Next_Instance_W_Condition
( | Self | : not null access Ref; |
Received_Data | : not null access Data_Sequences.Sequence; | |
Info_Seq | : not null access DDS.SampleInfo_Seq.Sequence; | |
Max_Samples | : in DDS.Long := DDS.LENGTH_UNLIMITED; | |
Previous_Handle | : access constant DDS.InstanceHandle_T; | |
Condition | : DDS.ReadCondition.Ref_Access); |
procedure Take_Next_Instance_W_Condition
( | Self | : not null access Ref; |
Received_Data | : in out Data_Sequences.Sequence; | |
Info_Seq | : in out DDS.SampleInfo_Seq.Sequence; | |
Max_Samples | : in DDS.Long := DDS.LENGTH_UNLIMITED; | |
Previous_Handle | : access constant DDS.InstanceHandle_T; | |
Condition | : DDS.ReadCondition.Ref_Access); |
function Take_Next_Instance_W_Condition
( | Self | : not null access Ref; |
Max_Samples | : in DDS.Long := DDS.LENGTH_UNLIMITED; | |
Previous_Handle | : access constant DDS.InstanceHandle_T; | |
Condition | : DDS.ReadCondition.Ref_Access) return Container'Class; |
This operation accesses a collection of data values from the DDS.DataReader and 'removes' them from the DDS.DataReader.
The operation has the same behavior as FooDataReader.read_next_instance_w_condition, except that the samples are 'taken' from the DDS.DataReader such that they are no longer accessible via subsequent 'read' or 'take' operations.
Similar to the operation FooDataReader.read_next_instance, it is possible to call FooDataReader.take_next_instance_w_condition with a previous_handle that does not correspond to an instance currently managed by the DDS.DataReader.
The behavior of the FooDataReader.take_next_instance_w_condition operation follows the same rules as the FooDataReader.read operation regarding the pre-conditions and post-conditions for the received_data and sample_info. Similar to FooDataReader.read, the FooDataReader.take_next_instance_w_condition operation may 'loan' elements to the output collections, which must then be returned by means of FooDataReader.return_loan.
Similar to the FooDataReader.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 DDS.DataReader has no samples that meet the constraints, the procedure will fail with DDS.RETCODE_NO_DATA.
self: <<in>> Cannot be NULL
received_data: <<inout>> user data type-specific FooSeq object where the received data samples will be returned. Must be a valid non-NULL FooSeq. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
info_seq: <<inout>> a DDS.SampleInfoSeq object where the received sample info will be returned. Must be a valid non-NULL DDS.SampleInfoSeq. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
max_samples: <<in>> The maximum number of samples to be returned. If the special value DDS.LENGTH_UNLIMITED is provided, as many samples will be returned as are available, up to the limits described in the documentation for FooDataReader.take().
previous_handle: <<in>> The 'next smallest' instance with a value greater than this value that has available samples will be returned. Must be a valid non-NULL DDS.InstanceHandle_t. The procedure will fail with DDS.RETCODE_BAD_PARAMETER if it is NULL.
condition: <<in>> the DDS.ReadCondition to select samples of interest. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_PRECONDITION_NOT_MET, or DDS.RETCODE_NO_DATA, DDS.RETCODE_NOT_ENABLED.
See also: FooDataReader.take_next_instance
See also: DDS.LENGTH_UNLIMITED
procedure Return_Loan
( | Self | : not null access Ref; |
Received_Data | : not null access Data_Sequences.Sequence; | |
Info_Seq | : not null access DDS.SampleInfo_Seq.Sequence); |
procedure Return_Loan
( | Self | : not null access Ref; |
Received_Data | : in out Data_Sequences.Sequence; | |
Info_Seq | : in out DDS.SampleInfo_Seq.Sequence); |
procedure Get_Key_Value
( | Self | : not null access Ref; |
Key_Holder | : not null Data_Type_Access; | |
Handle | : access constant DDS.InstanceHandle_T); |
procedure Get_Key_Value
( | Self | : not null access Ref; |
Key_Holder | : out Data_Type; | |
Handle | : access constant DDS.InstanceHandle_T); |
procedure Get_Key_Value
( | Self | : not null access Ref; |
Key_Holder | : out Data_Type; | |
Handle | : in DDS.InstanceHandle_T); |
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 DDS.RETCODE_BAD_PARAMETER if the handle does not correspond to an existing data-object known to the DDS.DataReader.
self: <<in>> Cannot be NULL
key_holder: <<inout>> a user data type specific key holder, whose key fields are filled by this operation. If Foo has no key, this procedure has no effect. This procedure will fail with DDS.RETCODE_BAD_PARAMETER if key_holder is NULL.
handle: <<in>> the instance whose key is to be retrieved. If Foo has a key, handle must represent an existing instance of type Foo known to the DDS.DataReader. Otherwise, this procedure will fail with DDS.RETCODE_BAD_PARAMETER.
If Foo has a key and handle is DDS_HANDLE_NIL, this procedure will fail with DDS.RETCODE_BAD_PARAMETER.
If Foo has a key and handle represents an instance of another type or an instance of type Foo that has been unregistered, this procedure will fail with DDS.RETCODE_BAD_PARAMETER. If Foo has no key, this procedure has no effect.
This procedure will fail with DDS.RETCODE_BAD_PARAMETER if handle is NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes or DDS.RETCODE_NOT_ENABLED.
See also: FooDataWriter.get_key_value
function Lookup_Instance
( | Self | : not null access Ref; |
Key_Holder | : not null Data_Type_Access) return DDS.InstanceHandle_T; |
function Lookup_Instance
( | Self | : not null access Ref; |
Key_Holder | : Data_Type) return DDS.InstanceHandle_T; |
procedure Lookup_Instance
( | Self | : not null access Ref; |
Key_Holder | : Data_Type; | |
Instance | : out DDS.InstanceHandle_T); |
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 DDS_HANDLE_NIL.
self: <<in>> Cannot be NULL
key_holder: <<in>> a user data type specific key holder.
Returns: the instance handle associated with this instance. If Foo has no key, this procedure has no effect and returns DDS_HANDLE_NIL
function As_DataReader
( | Self | : Ref_Access) return Standard.DDS.DataReader.Ref_Access is (Standard.DDS.DataReader.Ref_Access (Self)); |
function Narrow
( | Self | : access DDS.DataReader.Ref'Class) return not null access Ref is (Ref (Self.all)'Access); |
function CreateTypedI return DDS.DataReader.Ref_Access;
procedure DestroyTypedI
( | Reader | : in out DDS.DataReader.Ref_Access); |