Index

Package: DDS.DataReader

Description

package DDS.DataReader is

Summary: <<interface>> 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.

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:

  • The base-class operations DDS.DataReader.set_qos, DDS.DataReader.get_qos, DDS.DataReader.set_listener, DDS.DataReader.get_listener, DDS.Entity.enable, DDS.Entity.get_statuscondition, DDS.Entity.get_status_changes,
  • DDS.DataReader.get_liveliness_changed_status, DDS.DataReader.get_requested_deadline_missed_status, DDS.DataReader.get_requested_incompatible_qos_status, DDS.DataReader.get_sample_lost_status, DDS.DataReader.get_sample_rejected_status, DDS.DataReader.get_subscription_matched_status

    \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

    • Types

    Ref (abstract) 

    type Ref is limited interface and DDS.Domain_Entity.Ref;

    Ref_Access 

    type Ref_Access is access all Ref'Class;

    Ref_Access_Access 

    type Ref_Access_Access is access all Ref_Access;

    Ref_Access_Array 

    type Ref_Access_Array is array (Natural range <>) of aliased Ref_Access;

    Subprograms & Entries

    Initialize 

    procedure Initialize 
    (Self: in out Ref_Access) is null;

    Finalize 

    procedure Finalize 
    (Self: in out Ref_Access) is null;

    Copy 

    procedure Copy 
    (Dst: in out Ref_Access;
    Src: in Ref_Access);

    Create_Readcondition (abstract) 

    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;

    Summary: Creates a DDS.ReadCondition.

    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.

    Create_Querycondition (abstract) 

    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;

    Summary: Creates a DDS.QueryCondition.

    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.

    Create_IndexCondition (abstract) 

    function Create_IndexCondition 
    (Self: not null access Ref;
    Index_Name: in DDS.String;
    Sample_State: in DDS.SampleStateMask;
    view_state: in DDS.ViewStateMask;
    instance_state: in DDS.InstanceStateMask;
    Sample_Info: in DDS.SampleInfo) return DDS.IndexCondition.Ref_Access is abstract;

    Delete_Readcondition (abstract) 

    procedure Delete_Readcondition 
    (Self: not null access Ref;
    A_Condition: access DDS.ReadCondition.Ref'Class) is abstract;

    Summary: Deletes a DDS.ReadCondition or DDS.QueryCondition attached to the DDS.DataReader.

    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

    Delete_Contained_Entities (abstract) 

    procedure  Delete_Contained_Entities 
    (Self: not null access Ref) is abstract;

    Summary: Deletes all the entities that were created by means of the "create" operations on the DDS.DataReader.

    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

    Set_Qos (abstract) 

    procedure Set_Qos 
    (Self: not null access Ref;
    Qos: in DDS.DataReaderQoS) is abstract;

    Summary: Sets the reader QoS.

    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

    Set_Qos_With_Profile (abstract) 

    procedure Set_Qos_With_Profile 
    (Self: not null access Ref;
    library_name: in String;
    profile_name: in String) is abstract;

    Set_Qos_With_Profile (abstract) 

    procedure Set_Qos_With_Profile 
    (Self: not null access Ref;
    library_name: in Standard.String;
    profile_name: in Standard.String) is abstract;

    Summary: <<ext>> Changes the QoS of this reader using the input XML QoS profile.

    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

    Get_Qos (abstract) 

    procedure Get_Qos 
    (Self: not null access Ref;
    Qos: in out DDS.DataReaderQoS) is abstract;

    Summary: Gets the reader QoS.

    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

    Set_Listener (abstract) 

    procedure Set_Listener 
    (Self: not null access Ref;
    A_Listener: in DDS.DataReaderListener.Ref_Access;
    Mask: in DDS.StatusMask) is abstract;

    Summary: Sets the reader listener.

    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

    Get_Listener (abstract) 

    function Get_Listener 
    (Self: not null access Ref) return DDS.DataReaderListener.Ref_Access is abstract;

    Summary: Gets the reader listener.

    self: <<in>> Cannot be NULL

    Returns: DDS.DataReaderListener of the DDS.DataReader.


    See also: Entity_get_listener

    Call_ListnerT (abstract) 

    procedure Call_ListnerT 
    (Self: not null access Ref;
    A_Listener: in DDS.DataReaderListener.Ref_Access;
    Mask: in DDS.StatusMask) is abstract;

    Get_Topicdescription (abstract) 

    function Get_Topicdescription 
    (Self: not null access Ref) return DDS.TopicDescription.Ref_Access is abstract;

    Summary: Returns the DDS.TopicDescription associated with the DDS.DataReader.

    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.

    Get_Subscriber (abstract) 

    function Get_Subscriber 
    (Self: not null access Ref) return access DDS.Subscriber.Ref'Class is abstract;

    Summary: Returns the DDS.Subscriber to which the DDS.DataReader belongs.

    self: <<in>> Cannot be NULL

    Returns: DDS.Subscriber to which the DDS.DataReader belongs.

    Get_Sample_Rejected_Status (abstract) 

    procedure Get_Sample_Rejected_Status 
    (Self: not null access Ref;
    Status: in out DDS.SampleRejectedStatus) is abstract;

    Summary: Accesses the DDS.SAMPLE_REJECTED_STATUS communication status.

    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

    Get_Liveliness_Changed_Status (abstract) 

    procedure Get_Liveliness_Changed_Status 
    (Self: not null access Ref;
    Status: in out DDS.LivelinessChangedStatus) is abstract;

    Summary: Accesses the DDS.LIVELINESS_CHANGED_STATUS communication status.

    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

    Get_Requested_Deadline_Missed_Status (abstract) 

    procedure Get_Requested_Deadline_Missed_Status 
    (Self: not null access Ref;
    Status: in out DDS.RequestedDeadlineMissedStatus) is abstract;

    Summary: Accesses the DDS.REQUESTED_DEADLINE_MISSED_STATUS communication status.

    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

    Get_Requested_Incompatible_Qos_Status (abstract) 

    procedure Get_Requested_Incompatible_Qos_Status 
    (Self: not null access Ref;
    Status: in out DDS.RequestedIncompatibleQosStatus) is abstract;

    Summary: Accesses the DDS.REQUESTED_INCOMPATIBLE_QOS_STATUS communication status.

    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

    Get_Subscription_Matched_Status (abstract) 

    procedure Get_Subscription_Matched_Status 
    (Self: not null access Ref;
    Status: in out DDS.SubscriptionMatchedStatus) is abstract;

    Summary: Accesses the DDS.SUBSCRIPTION_MATCHED_STATUS communication status.

    self: <<in>> Cannot be NULL

    status: <<inout>> DDS.SubscriptionMatchedStatus to be filled in. Cannot be NULL.

    Raises: One of the DDSReturnTypesModules_std_retcodes

    Get_Sample_Lost_Status (abstract) 

    procedure Get_Sample_Lost_Status 
    (Self: not null access Ref;
    Status: in out DDS.SampleLostStatus) is abstract;

    Summary: Accesses the DDS.SAMPLE_LOST_STATUS communication status.

    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

    Get_Datareader_Cache_Status (abstract) 

    procedure Get_Datareader_Cache_Status 
    (Self: not null access Ref;
    Status: in out DDS.DataReaderCacheStatus) is abstract;

    Summary: <<ext>> Gets the datareader cache status for this reader.

    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.

    Get_Datareader_Protocol_Status (abstract) 

    procedure Get_Datareader_Protocol_Status 
    (Self: not null access Ref;
    Status: in out DDS.DataReaderProtocolStatus) is abstract;

    Summary: <<ext>> Gets the datareader protocol status for this reader.

    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.

    Get_Matched_Publication_Datareader_Protocol_Status (abstract) 

    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;

    Summary: <<ext>> Gets the datareader protocol status for this reader, per matched publication identified by the publication_handle.

    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

    Wait_For_Historical_Data (abstract) 

    procedure Wait_For_Historical_Data 
    (Self: not null access Ref;
    Max_Wait: in DDS.Duration_T) is abstract;

    Summary: Waits until all "historical" data is received for DDS.DataReader entities that have a non-VOLATILE Durability Qos kind.

    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.

    Get_Matched_Publications (abstract) 

    function Get_Matched_Publications 
    (Self: not null access Ref) return DDS.InstanceHandle_Seq.Sequence is abstract;

    Summary: Retrieves the list of publications currently "associated" with this DDS.DataReader.

    A publication is considered to be matching if all of the following criteria are true:

  • The publication is within the same domain as this subscription.
  • The publication has a matching DDS.Topic.
  • The publication has compatible QoS.
  • If the applications are using partitions, the publication shares a common partition with this subscription.
  • The DDS.DomainParticipant has not indicated that the publication's DDS.DomainParticipant should be "ignored" by means of the DDS.DomainParticipant.ignore_publication API.
  • If the subscription is using a DDS.ContentFilteredTopic and the publication is using the DDS.MultiChannelQosPolicy, there is an intersection between at least one of the associated filters.
  • If the endpoints need to exchange key material to communicate (i.e., they are securing their communications), the reader has completed the key exchange with the writer.

    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

    • Get_Matched_Publication_Data (abstract) 

    function Get_Matched_Publication_Data 
    (Self: not null access Ref;
    Publication_Handle: not null access DDS.InstanceHandle_T) return DDS.PublicationBuiltinTopicData is abstract;

    Summary: Retrieves the information on a publication that is currently "associated" with the DDS.DataReader.

    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

    call_listener (abstract) 

    procedure  call_listener 
    (Self: not null access Ref;
    mask: StatusMask) is abstract;

    set_liveliness_changed_status (abstract) 

    procedure  set_liveliness_changed_status 
    (Self: not null access Ref;
    To: LivelinessChangedStatus) is abstract;

    Read_Or_Take_W_Condition_UntypedI (abstract) 

    function Read_Or_Take_W_Condition_UntypedI 
    (Self: not null access constant Ref;
    Is_Loan: access DDS.Boolean;
    Received_Data: System.Address;
    Data_Count: access Natural;
    Info_Seq: SampleInfo_Seq.Sequence;
    Data_Seq_Len: Long_Integer;
    Data_Seq_Max_Len: Long_Integer;
    Data_Seq_Has_Ownership: Long_Integer;
    Data_Seq_Contiguous_Buffer_For_Copy: System.Address;
    Data_Size: Integer;
    Max_Samples: Long_Integer;
    Condition: not null access DDS.ReadCondition.Ref'Class;
    Take: DDS.Boolean) return  DDS.ReturnCode_T is abstract;

    Return_Loan_UntypedI (abstract) 

    function Return_Loan_UntypedI 
    (Self: not null access constant Ref;
    Received_Data: System.Address;
    Data_Count: Natural;
    Info_Seq: Standard.DDS.SampleInfo_Seq.Sequence) return DDS.ReturnCode_T is abstract;

    Return_Loan_UntypedI (abstract) 

    procedure Return_Loan_UntypedI 
    (Self: not null access constant Ref;
    Received_Data: System.Address;
    Data_Count: Natural;
    Info_Seq: Standard.DDS.SampleInfo_Seq.Sequence) is abstract;