type Ref is limited interface and DDS.Domain_Entity.Ref;
type Ref_Access is access all Ref'Class;
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; |
The returned DDS.ReadCondition will be attached and belong to the DDS.DataReader.
self: <<in>> Cannot be NULL
sample_states: <<in>> sample state of the data samples that are of interest
view_states: <<in>> view state of the data samples that are of interest
instance_states: <<in>> instance state of the data samples that are of interest
Returns: return DDS.ReadCondition created. Returns NULL in case of failure.
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; |
The returned DDS.QueryCondition will be attached and belong to the DDS.DataReader.
DDSQueryAndFilterSyntaxModule describes the syntax of query_expression and query_parameters.
self: <<in>> Cannot be NULL
sample_states: <<in>> sample state of the data samples that are of interest
view_states: <<in>> view state of the data samples that are of interest
instance_states: <<in>> instance state of the data samples that are of interest
query_expression: <<in>> Expression for the query. Cannot be NULL.
query_parameters: <<in>> Parameters for the query expression. Cannot be NULL.
Returns: return DDS.QueryCondition created. Returns NULL in case of failure.
procedure Delete_Readcondition
( | Self | : not null access Ref; |
A_Condition | : access DDS.ReadCondition.Ref'Class) is abstract; |
Since DDS.QueryCondition specializes DDS.ReadCondition, it can also be used to delete a DDS.QueryCondition.
Precondition: The DDS.ReadCondition must be attached to the DDS.DataReader, or the operation will fail with the error DDS.RETCODE_PRECONDITION_NOT_MET.
@mtsafety_delete
self: <<in>> Cannot be NULL
condition: <<in>> Condition to be deleted.
Raises: One of the DDSReturnTypesModules_std_retcodes, or DDS.RETCODE_PRECONDITION_NOT_MET
procedure Delete_Contained_Entities
( | Self | : not null access Ref) is abstract; |
Deletes all contained DDS.ReadCondition, DDS.QueryCondition, and DDS.TopicQuery objects.
The operation will fail with DDS.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.
@mtsafety_delete
self: <<in>> Cannot be NULL
Raises: One of the DDSReturnTypesModules_std_retcodes, or DDS.RETCODE_PRECONDITION_NOT_MET
procedure Set_Qos
( | Self | : not null access Ref; |
Qos | : in DDS.DataReaderQoS) is abstract; |
Modifies the QoS of the DDS.DataReader.
The DDS.DataReaderQos.user_data, DDS.DataReaderQos.deadline, DDS.DataReaderQos.latency_budget, DDS.DataReaderQos.time_based_filter, DDS.DataReaderQos.reader_data_lifecycle can be changed. The other policies are immutable.
self: <<in>> Cannot be NULL
qos: <<in>> The DDS.DataReaderQos to be set to. Policies must be consistent. Immutable policies cannot be changed after DDS.DataReader is enabled. The special value DDS.DATAREADER_QOS_DEFAULT can be used to indicate that the QoS of the DDS.DataReader should be changed to match the current default DDS.DataReaderQos set in the DDS.Subscriber. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_IMMUTABLE_POLICY, or DDS.RETCODE_INCONSISTENT_POLICY.
See also: DDS.DataReaderQos for rules on consistency among QoS
See also: Entity_set_qos
See also: DDS.DataReader.set_qos
See also: SharedEACallbackRules
procedure Set_Qos_With_Profile
( | Self | : not null access Ref; |
library_name | : in Standard.String; | |
profile_name | : in Standard.String) is abstract; |
This operation modifies the QoS of the DDS.DataReader.
The DDS.DataReaderQos.user_data, DDS.DataReaderQos.deadline, DDS.DataReaderQos.latency_budget, DDS.DataReaderQos.time_based_filter, DDS.DataReaderQos.reader_data_lifecycle can be changed. The other policies are immutable.
self: <<in>> Cannot be NULL
library_name: <<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see DDS.Subscriber.set_default_library).
profile_name: <<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see DDS.Subscriber.set_default_profile).
Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_IMMUTABLE_POLICY, or DDS.RETCODE_INCONSISTENT_POLICY.
See also: DDS.DataReaderQos for rules on consistency among QoS
See also: DDS.DataReader.set_qos
See also: SharedEACallbackRules
procedure Get_Qos
( | Self | : not null access Ref; |
Qos | : in out DDS.DataReaderQoS) is abstract; |
This procedure may potentially allocate memory depending on the sequences contained in some QoS policies.
self: <<in>> Cannot be NULL
qos: <<inout>> The DDS.DataReaderQos to be filled up. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes
See also: Entity_get_qos
procedure Set_Listener
( | Self | : not null access Ref; |
A_Listener | : in DDS.DataReaderListener.Ref_Access; | |
Mask | : in DDS.StatusMask) is abstract; |
self: <<in>> Cannot be NULL
l: <<in>> DDS.DataReaderListener to set to
mask: <<in>> DDS.StatusMask associated with the DDS.DataReaderListener.
Raises: One of the DDSReturnTypesModules_std_retcodes
See also: Entity_set_listener
function Get_Listener
( | Self | : not null access Ref) return DDS.DataReaderListener.Ref_Access is abstract; |
self: <<in>> Cannot be NULL
Returns: DDS.DataReaderListener of the DDS.DataReader.
See also: Entity_get_listener
procedure Call_ListnerT
( | Self | : not null access Ref; |
A_Listener | : in DDS.DataReaderListener.Ref_Access; | |
Mask | : in DDS.StatusMask) is abstract; |
function Get_Topicdescription
( | Self | : not null access Ref) return DDS.TopicDescription.Ref_Access is abstract; |
Returns that same DDS.TopicDescription that was used to create the DDS.DataReader.
self: <<in>> Cannot be NULL
Returns: DDS.TopicDescription associated with the DDS.DataReader.
function Get_Subscriber
( | Self | : not null access Ref) return access DDS.Subscriber.Ref'Class is abstract; |
self: <<in>> Cannot be NULL
Returns: DDS.Subscriber to which the DDS.DataReader belongs.
procedure Get_Sample_Rejected_Status
( | Self | : not null access Ref; |
Status | : in out DDS.SampleRejectedStatus) is abstract; |
This also resets the status so that it is no longer considered changed.
self: <<in>> Cannot be NULL
status: <<inout>> DDS.SampleRejectedStatus to be filled in. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes
procedure Get_Liveliness_Changed_Status
( | Self | : not null access Ref; |
Status | : in out DDS.LivelinessChangedStatus) is abstract; |
This also resets the status so that it is no longer considered changed.
self: <<in>> Cannot be NULL
status: <<inout>> DDS.LivelinessChangedStatus to be filled in. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes
procedure Get_Requested_Deadline_Missed_Status
( | Self | : not null access Ref; |
Status | : in out DDS.RequestedDeadlineMissedStatus) is abstract; |
This also resets the status so that it is no longer considered changed.
self: <<in>> Cannot be NULL
status: <<inout>> DDS.RequestedDeadlineMissedStatus to be filled in. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes
procedure Get_Requested_Incompatible_Qos_Status
( | Self | : not null access Ref; |
Status | : in out DDS.RequestedIncompatibleQosStatus) is abstract; |
This also resets the status so that it is no longer considered changed.
self: <<in>> Cannot be NULL
status: <<inout>> DDS.RequestedIncompatibleQosStatus to be filled in. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes
procedure Get_Subscription_Matched_Status
( | Self | : not null access Ref; |
Status | : in out DDS.SubscriptionMatchedStatus) is abstract; |
self: <<in>> Cannot be NULL
status: <<inout>> DDS.SubscriptionMatchedStatus to be filled in. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes
procedure Get_Sample_Lost_Status
( | Self | : not null access Ref; |
Status | : in out DDS.SampleLostStatus) is abstract; |
This also resets the status so that it is no longer considered changed.
self: <<in>> Cannot be NULL
status: <<inout>> DDS.SampleLostStatus to be filled in. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes
procedure Get_Datareader_Cache_Status
( | Self | : not null access Ref; |
Status | : in out DDS.DataReaderCacheStatus) is abstract; |
self: <<in>> Cannot be NULL
status: <<inout>> DDS.DataReaderCacheStatus to be filled in. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes or DDS.RETCODE_NOT_ENABLED.
procedure Get_Datareader_Protocol_Status
( | Self | : not null access Ref; |
Status | : in out DDS.DataReaderProtocolStatus) is abstract; |
This also resets the status so that it is no longer considered changed.
self: <<in>> Cannot be NULL
status: <<inout>> DDS.DataReaderProtocolStatus to be filled in. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes or DDS.RETCODE_NOT_ENABLED.
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; |
This also resets the status so that it is no longer considered changed.
Note: Status for a remote entity is only kept while the entity is alive. Once a remote entity is no longer alive, its status is deleted.
self: <<in>> Cannot be NULL
status: <<inout>>. The information to be filled in on the associated publication. Cannot be NULL.
publication_handle: <<in>>. Handle to a specific publication associated with the DDS.DataWriter. Cannot be NULL.. Must correspond to a publication currently associated with the DDS.DataReader.
Raises: One of the DDSReturnTypesModules_std_retcodes or DDS.RETCODE_NOT_ENABLED
procedure Wait_For_Historical_Data
( | Self | : not null access Ref; |
Max_Wait | : in DDS.Duration_T) is abstract; |
This operation is intended only for DDS.DataReader entities that have a non-VOLATILE Durability 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.
DDS.DataReader.wait_for_historical_data() blocks the calling thread until either all "historical" data is received, or until the duration specified by the max_wait parameter elapses, whichever happens first. It will return immediately if no DataWriters have been discovered at the time the operation is called; therefore it is advisable to make sure at least one DDS.DataWriter has been discovered before calling this operation. (One way to do this is by using DDS.DataReader.get_subscription_matched_status.)
A successful completion indicates that all the "historical" data was "received"; timing out indicates that max_wait elapsed before all the data was received.
self: <<in>> Cannot be NULL
max_wait: <<in>> Timeout value. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_TIMEOUT or DDS.RETCODE_NOT_ENABLED.
function Get_Matched_Publications
( | Self | : not null access Ref) return DDS.InstanceHandle_Seq.Sequence is abstract; |
A publication is considered to be matching if all of the following criteria are true:
The handles returned in the publication_handles list are the ones that are used by the RTI Connext implementation to locally identify the corresponding matched DDS.DataWriter entities. These handles match the ones that appear in the instance_handle field of the DDS.SampleInfo when reading the DDS.PUBLICATION_TOPIC_NAME builtin topic.
This API may return the publication handles of publications that are not alive. DDS.DataReader.is_matched_publication_alive can be used to check the liveliness of the remote publication.
self: <<in>> Cannot be NULL
publication_handles: <<inout>>. 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 of the matches and the system cannot resize the sequence, this procedure will fail with DDS.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. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes, or DDS.RETCODE_OUT_OF_RESOURCES if the sequence is too small and the system cannot resize it, or DDS.RETCODE_NOT_ENABLED
function Get_Matched_Publication_Data
( | Self | : not null access Ref; |
Publication_Handle | : not null access DDS.InstanceHandle_T) return DDS.PublicationBuiltinTopicData is abstract; |
The publication_handle must correspond to a publication currently associated with the DDS.DataReader. Otherwise, the operation will fail with DDS.RETCODE_BAD_PARAMETER. Use the operation DDS.DataReader.get_matched_publications to find the publications that are currently matched with the DDS.DataReader.
Note: This operation does not retrieve the DDS.PublicationBuiltinTopicData.type_code. This information is available through DDS.DataReaderListener::on_data_available() (if a reader listener is installed on the DDS.PublicationBuiltinTopicDataDataReader).
self: <<in>> Cannot be NULL
publication_data: <<inout>>. The information to be filled in on the associated publication. Cannot be NULL.
publication_handle: <<in>>. Handle to a specific publication associated with the DDS.DataWriter. Must correspond to a publication currently associated with the DDS.DataReader. Cannot be NULL.
Raises: One of the DDSReturnTypesModules_std_retcodes or DDS.RETCODE_NOT_ENABLED
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; |
QoS:
DDS.DataReaderQos
Status:
DDS.DATA_AVAILABLE_STATUS;
DDS.LIVELINESS_CHANGED_STATUS, DDS.LivelinessChangedStatus;
DDS.REQUESTED_DEADLINE_MISSED_STATUS, DDS.RequestedDeadlineMissedStatus;
DDS.REQUESTED_INCOMPATIBLE_QOS_STATUS, DDS.RequestedIncompatibleQosStatus;
DDS.SAMPLE_LOST_STATUS, DDS.SampleLostStatus;
DDS.SAMPLE_REJECTED_STATUS, DDS.SampleRejectedStatus;
DDS.SUBSCRIPTION_MATCHED_STATUS, DDS.SubscriptionMatchedStatus;
Listener:
DDS.DataReaderListener
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 DDSUserDataQosModule). 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 FooDataReader. \endif
The following operations may be called even if the DDS.DataReader is not enabled. Other operations will fail with the value DDS.RETCODE_NOT_ENABLED if called on a disabled DDS.DataReader:
\ifnot CPP2_LANGUAGE_ONLY All sample-accessing operations, namely: FooDataReader.read, FooDataReader.take, FooDataReader.read_w_condition, and FooDataReader.take_w_condition may fail with the error DDS.RETCODE_PRECONDITION_NOT_MET as described in DDS.Subscriber.begin_access.
See also: SharedEACallbackRules
See also: Subscription_access_samples