pragma Ada_2012;
-- (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.
limited with DDS.Subscriber;
with DDS.TopicDescription;
with DDS.DataReaderListener;
with DDS.QueryCondition;
with DDS.ReadCondition;
with DDS.Domain_Entity;
with DDS.MetpTypeSupport;
-- <dref>DataReader</dref>
package DDS.DataReader is
type Ref is limited interface and DDS.Domain_Entity.Ref;
type Ref_Access is access all Ref'Class;
-- Allows the application to:
-- (1) declare the data it wishes to receive (i.e. make a subscription) and
-- (2) access the data received by the attached DDS.Subscriber.
--
-- A DDS.DataReader refers to exactly one DDS.TopicDescription
-- (either a DDS.Topic, a DDS.ContentFilteredTopic or a DDS.MultiTopic)
-- that identifies the data to be read.
-- The subscription has a unique resulting type. The data-reader may give
-- access to several instances of the resulting type,
-- which can be distinguished from each other by their key.
--
-- DDS.DataReader is an abstract class.
-- It must be specialised for each particular application data-type
-- (see USER_DATA). The additional methods or functions that must be defined
-- in the auto-generated class for a hypothetical application type Foo are
-- specified in the generic type DDS.example.FooDataReader.
--
-- The following operations may be called even if the DDS.DataReader
-- is not enabled. Other operations will fail with
-- exception RETCODE_NOT_ENABLED if called on a disabled DDS.DataReader:
--
-- See also:
-- Operations Allowed in Listener Callbacks
type Ref_Access_Access is access all Ref_Access;
type Ref_Access_Array is array (Natural range <>) of aliased Ref_Access;
procedure Initialize
(Self : in out Ref_Access) is null;
procedure Finalize
(Self : in out Ref_Access) is null;
procedure Copy
(Dst : in out Ref_Access;
Src : in Ref_Access);
function Create_Readcondition
(Self : not null access Ref;
Sample_States : in DDS.SampleStateMask;
View_States : in DDS.ViewStateMask;
Instance_States : in DDS.InstanceStateMask)
return DDS.ReadCondition.Ref_Access is abstract;
-- <dref>DataReader_create_readcondition</dref>
-- <internal>
-- The returned DDS.ReadCondition will be
-- attached and belong to the DDS.DataReader.
-- </internal>
function Create_Querycondition
(Self : not null access Ref;
Sample_States : in DDS.SampleStateMask;
View_States : in DDS.ViewStateMask;
Instance_States : in DDS.InstanceStateMask;
Query_Expression : in DDS.String;
Query_Parameters : in DDS.String_Seq.Sequence)
return DDS.QueryCondition.Ref_Access is abstract;
-- <dref>DataReader_create_querycondition</dref>
-- <internal>
-- Not supported (optional>> Creates a DDS.QueryCondition.
-- The returned DDS.QueryCondition will be attached
-- and belong to the DDS.DataReader.
-- Queries and Filters Syntax describes the syntax of
-- query_expression and query_parameter
-- </internal>
procedure Delete_Readcondition
(Self : not null access Ref;
A_Condition : access DDS.ReadCondition.Ref'Class) is abstract;
-- <dref>DataReader_delete_readcondition</dref>
procedure Delete_Contained_Entities
(Self : not null access Ref) is abstract;
-- <dref>DataReader_delete_contained_entities</dref>
-- <internal>
-- Deletes all the entities that were created by means of the "create"
-- operations on the dds.DataReader.
-- Deletes all contained dds.ReadCondition and dds.QueryCondition objects.
-- The operation will fail with RETCODE_PRECONDITION_NOT_MET if the any of
-- the contained entities is in a state where it cannot be deleted.
-- Once dds.DataReader.delete_contained_entities completes successfully,
-- the application may delete the dds.DataReader, knowing that it has no
-- contained dds.ReadCondition and dds.QueryCondition objects.
-- </internal>
procedure Set_Qos
(Self : not null access Ref;
Qos : in DDS.DataReaderQoS) is abstract;
-- <dref>DataReader_set_qos</dref>
procedure Set_Qos_With_Profile
(Self : not null access Ref;
library_name : in String;
profile_name : in String) is abstract;
procedure Set_Qos_With_Profile
(Self : not null access Ref;
library_name : in Standard.String;
profile_name : in Standard.String) is abstract;
-- <dref>DataReader_set_qos_with_profile</dref>
-- <internal>
-- This operation modifies the QoS of the DDS.DataReader.
-- The DataReaderQos.user_data,
-- DataReaderQos.deadline,
-- DataReaderQos.latency_budget,
-- DataReaderQos.time_based_filter,
-- DataReaderQos.reader_data_lifecycle
-- can be changed.
-- The other policies are immutable.
-- </internal>
procedure Get_Qos
(Self : not null access Ref;
Qos : in out DDS.DataReaderQoS) is abstract;
-- <dref>DataReader_get_qos</dref>
-- <internal>
-- Gets the reader QoS.
-- This method may potentially allocate memory depending on the sequences
-- contained in some QoS policies
-- </internal>
procedure Set_Listener
(Self : not null access Ref;
A_Listener : in DDS.DataReaderListener.Ref_Access;
Mask : in DDS.StatusMask) is abstract;
-- <dref>DataReader_set_listener</dref>
-- <internal>
-- Sets the reader listener.
-- </internal>
function Get_Listener
(Self : not null access Ref)
return DDS.DataReaderListener.Ref_Access is abstract;
-- <dref>DataReader_get_listener</dref>
-- <internal>
-- Get the reader listener
-- </internal>
procedure Call_ListnerT
(Self : not null access Ref;
A_Listener : in DDS.DataReaderListener.Ref_Access;
Mask : in DDS.StatusMask) is abstract;
-- <internal>
-- Calls the reader listener.
-- </internal>
function Get_Topicdescription
(Self : not null access Ref)
return DDS.TopicDescription.Ref_Access is abstract;
-- <dref>DataReader_get_topicdescription</dref>
-- <internal>
-- Returns the dds.TopicDescription associated with the dds.DataReader.
-- </internal>
function Get_Subscriber
(Self : not null access Ref)
return access DDS.Subscriber.Ref'Class is abstract;
-- <dref>DataReader_get_subscriber</dref>
-- <internal>
-- Returns the dds.Subscriber to which the dds.DataReader belongs.
-- </internal>
procedure Get_Sample_Rejected_Status
(Self : not null access Ref;
Status : in out DDS.SampleRejectedStatus) is abstract;
-- <dref>DataReader_get_sample_rejected_status</dref>
-- <internal>
-- Return the StatusKind.SAMPLE_REJECTED_STATUS communication status.
-- </internal>
procedure Get_Liveliness_Changed_Status
(Self : not null access Ref;
Status : in out DDS.LivelinessChangedStatus) is abstract;
-- <dref>DataReader_get_liveliness_changed_status</dref>
-- <internal>
-- Returns the StatusKind.LIVELINESS_CHANGED_STATUS communication status.
-- </internal>
procedure Get_Requested_Deadline_Missed_Status
(Self : not null access Ref;
Status : in out DDS.RequestedDeadlineMissedStatus) is abstract;
-- <dref>DataReader_get_requested_deadline_missed_status</dref>
-- <internal>
-- Returns the StatusKind.REQUESTED_DEADLINE_MISSED_STATUS
-- communication status.
-- </internal>
procedure Get_Requested_Incompatible_Qos_Status
(Self : not null access Ref;
Status : in out DDS.RequestedIncompatibleQosStatus) is abstract;
-- <dref>DataReader_get_requested_incompatible_qos_status</dref>
-- <internal>
-- Returns the StatusKind.REQUESTED_INCOMPATIBLE_QOS_STATUS
-- communication status
-- </internal>
procedure Get_Subscription_Matched_Status
(Self : not null access Ref;
Status : in out DDS.SubscriptionMatchedStatus) is abstract;
-- <dref>DataReader_get_subscription_matched_status</dref>
-- <internal>
-- Returns the StatusKind.SUBSCRIPTION_MATCHED_STATUS communication status.
-- </internal>
procedure Get_Sample_Lost_Status
(Self : not null access Ref;
Status : in out DDS.SampleLostStatus) is abstract;
-- <dref>DataReader_get_sample_lost_status</dref>
-- <internal>
-- Returns the StatusKind.SAMPLE_LOST_STATUS_STATUS communication status
-- </internal>
procedure Get_Datareader_Cache_Status
(Self : not null access Ref;
Status : in out DDS.DataReaderCacheStatus) is abstract;
-- <dref>DataReader_get_datareader_cache_status</dref>
-- <internal>
-- Returns the StatusKind.DATA_READER_CACHE_STATUS communication status
-- </internal>
procedure Get_Datareader_Protocol_Status
(Self : not null access Ref;
Status : in out DDS.DataReaderProtocolStatus) is abstract;
-- <dref>DataReader_get_datareader_protocol_status</dref>
-- <internal>
-- Returns the StatusKind.DATA_READER_PROTOCOL_STATUS communication status
-- </internal>
procedure Get_Matched_Publication_Datareader_Protocol_Status
(Self : not null access Ref;
Status : in out DDS.DataReaderProtocolStatus;
Publication_Handle : not null access DDS.InstanceHandle_T) is abstract;
-- <dref>DataReader_get_matched_publication_datareader_protocol_status</dref>
-- <internal>
-- Returns the StatusKind.DATA_READER_PROTOCOL_STATUS communication status
-- for this reader, per matched publication identified by the
-- Publication_Handle.
-- </internal>
procedure Wait_For_Historical_Data
(Self : not null access Ref;
Max_Wait : in DDS.Duration_T) is abstract;
-- <dref>DataReader_wait_for_historical_data</dref>
-- <internal>
-- Waits until all "historical" data is received for dds.DataReader entities
-- that have a non-VOLATILE PERSISTENCE Qos kind.
-- This operation is intended only for dds.DataReader entities that have a
-- non-VOLATILE PERSISTENCE QoS kind.
-- As soon as an application enables a non-VOLATILE dds.DataReader, it will
-- start receiving both "historical" data, i.e. the data that was written
-- prior to the time the dds.DataReader joined the domain, as well as any
-- new data written by the dds.DataWriter entities.
-- There are situations where the application logic may require the
-- application to wait until all "historical" data is received.
-- This is the purpose of the dds.DataReader.wait_for_historical_data operations.
-- The operation dds.DataReader.wait_for_historical_data blocks the calling
-- thread until either all "historical" data is received, or else duration
-- specified by the max_wait parameter clapses, whichever happens first.
-- A successful completion indicates that all the "historical" data was
-- "received"; timing out indicates that max_wait elapsed before all the
-- data was received
-- </internal>
function Get_Matched_Publications
(Self : not null access Ref)
return DDS.InstanceHandle_Seq.Sequence is abstract;
-- <dref>DataReader_get_matched_publications</dref>
-- <internal>
-- Retrieve the list of publications currently "associated" with this
-- DDS.DataReader.
-- Matching publications are those in the same domain that have a matching
-- DDS.Topic, compatible QoS common partition that the DDS.DomainParticipant
-- has not indicated should be "ignored" by means of the
-- DDS.DomainParticipant.ignore_publication operation.
-- The handles returned in the publication_handles' list are the ones that
-- are used by the DDS implementation to locally identify the corresponding
-- matched DDSDataWriter entities.
-- These handles match the ones that appear in the instance_handle field
-- of the DDS.SampleInfo when reading the
-- PublicationBuiltinTopicDataTypeSupport.PUBLICATION_TOPIC_NAME builtin topic
-- The sequence will be grown if the sequence has ownership and the system
-- has the corresponding resources. Use a sequence without ownership to
-- avoid dynamic memory allocation. If the sequence is too small to
-- store all the matches and the system can not resize the sequence,
-- this method will fail with RETCODE_OUT_OF_RESOURCES.
-- The maximum number of matches possible is configured with
-- DDS.DomainParticipantResourceLimitsQosPolicy.
-- You can use a zero-maximum sequence without ownership to quickly check
-- whether there are any matches without allocating any memory.
-- </internal>
function Get_Matched_Publication_Data
(Self : not null access Ref;
Publication_Handle : not null access DDS.InstanceHandle_T)
return DDS.PublicationBuiltinTopicData is abstract;
-- <dref>DataReader_get_matched_publication_data</dref>
-- <internal>
-- This operation retrieves the information on a publication that is
-- currently "associated" with the dds.DataReader.
-- Publication with a matching dds.Topic, compatible QoS and common
-- partition that the application has not indicated should be "ignored"
-- by means of the dds.DomainParticipant.ignore_publication operation.
-- The publication_handle must correspond to a publication currently
-- associated with the dds.DataReader. Otherwise, the operation will fail
-- with RETCODE_BAD_PARAMETER.
-- use the operation dds.DataReader.get_matched_publications to find the
-- publications that are currently matched with the DDS.DataReader.
-- </internal>
procedure call_listener
(Self : not null access Ref;
mask : StatusMask) is abstract;
procedure set_liveliness_changed_status
(Self : not null access Ref;
To : LivelinessChangedStatus) is abstract;
end DDS.DataReader;