Index

Package: DDS.Subscriber

Description

package DDS.Subscriber is

Summary: <<interface>> A subscriber is the object responsible for actually receiving data from a subscription.

QoS:
DDS.SubscriberQos

Status:
DDS.DATA_ON_READERS_STATUS

Listener:
DDS.SubscriberListener

A subscriber acts on the behalf of one or several DDS.DataReader objects that are related to it. When it receives data (from the other parts of the system), it builds the list of concerned DDS.DataReader objects and then indicates to the application that data is available through its listener or by enabling related conditions.

The application can access the list of concerned DDS.DataReader objects through the operation DDS.Subscriber.get_datareaders and then access the data available through operations on the DDS.DataReader.

The following operations may be called even if the DDS.Subscriber is not enabled. Other operations will the value DDS.RETCODE_NOT_ENABLED if called on a disabled DDS.Subscriber:

  • DDS.Entity.enable,
  • DDS.Subscriber.set_qos, DDS.Subscriber.get_qos , idref_Subscriber_set_qos_with_profile\endif
  • DDS.Subscriber.set_listener, DDS.Subscriber.get_listener,
  • DDS.Entity.get_statuscondition, DDS.Entity.get_status_changes
  • DDS.Subscriber.create_datareader, \ifnot CPP2_LANGUAGE_ONLY DDS.Subscriber.create_datareader_with_profile, DDS.Subscriber.delete_contained_entities, DDS.Subscriber.delete_datareader,
  • DDS.Subscriber.set_default_datareader_qos, DDS.Subscriber.set_default_datareader_qos_with_profile, DDS.Subscriber.get_default_datareader_qos, DDS.Subscriber.set_default_library, DDS.Subscriber.set_default_profile

    All operations except for DDS.Subscriber.set_qos, \ifnot CPP2_LANGUAGE_ONLY DDS.Subscriber.set_qos_with_profile,\endif DDS.Subscriber.get_qos, DDS.Subscriber.set_listener, DDS.Subscriber.get_listener, DDS.Entity.enable and DDS.Subscriber.create_datareader may fail with DDS.RETCODE_NOT_ENABLED.


    See also: SharedEACallbackRules

    • 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;

    Constants & Global variables

    DATAREADER_QOS_DEFAULT 

    DATAREADER_QOS_DEFAULT : aliased  constant DataReaderQoS with
     Convention => Ada,
     Import,
     Link_Name => "DDS__Subscriber_DATAREADER_QOS_DEFAULT";

    Summary: Special value for creating data reader with default QoS.

    When used in DDS.Subscriber.create_datareader, this special value is used to indicate that the DDS.DataReader should be created with the default DDS.DataReader QoS by means of the operation get_default_datareader_qos and using the resulting QoS to create the DDS.DataReader.

    When used in DDS.Subscriber.set_default_datareader_qos, this special value is used to indicate that the default QoS should be reset back to the initial value that would be used if the DDS.Subscriber.set_default_datareader_qos operation had never been called.

    When used in DDS.DataReader.set_qos, this special value is used to indicate that the QoS of the DDS.DataReader should be changed to match the current default QoS set in the DDS.Subscriber that the DDS.DataReader belongs to.

    Note: You cannot use this value to get the default QoS values for a DataReader; for this purpose, use DDS.DomainParticipant.get_default_datareader_qos.


    See also: DDS.Subscriber.create_datareader
    See also: DDS.Subscriber.set_default_datareader_qos
    See also: DDS.DataReader.set_qos

    DATAREADER_QOS_USE_TOPIC_QOS 

    DATAREADER_QOS_USE_TOPIC_QOS :  aliased  constant DataReaderQoS with
     Convention => Ada,
     Import,
     Link_Name => "DDS__Subscriber_DATAREADER_QOS_USE_TOPIC_QOS";

    Summary: Special value for creating DDS.DataReader with a combination of the default DDS.DataReaderQos and the DDS.TopicQos.

    The use of this value is equivalent to the application obtaining the default DDS.DataReaderQos and the DDS.TopicQos (by means of the operation DDS.Topic.get_qos) and then combining these two QoS using the operation DDS.Subscriber.copy_from_topic_qos whereby any policy that is set on the DDS.TopicQos "overrides" the corresponding policy on the default QoS. The resulting QoS is then applied to the creation of the DDS.DataReader.

    This value should only be used in DDS.Subscriber.create_datareader.


    See also: DDS.Subscriber.create_datareader
    See also: DDS.Subscriber.get_default_datareader_qos
    See also: DDS.Topic.get_qos
    See also: DDS.Subscriber.copy_from_topic_qos

    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_DataReader (abstract) 

    function Create_DataReader 
    (Self: not null access Ref;
    Topic: not null access DDS.TopicDescription.Ref'Class;
    Qos: in DDS.DataReaderQoS := DATAREADER_QOS_DEFAULT;
    A_Listener: in DDS.DataReaderListener.Ref_Access := null;
    Mask: in DDS.StatusMask := STATUS_MASK_NONE) return DDS.DataReader.Ref_Access is abstract;

    Summary: Creates a DDS.DataReader that will be attached and belong to the DDS.Subscriber.

    For each application-defined type Foo, there is an implied, auto-generated class FooDataReader (an incarnation of FooDataReader) that extends DDS.DataReader and contains the operations to read data of type Foo.

    Note that a common application pattern to construct the QoS for the DDS.DataReader is to:

  • Retrieve the QoS policies on the associated DDS.Topic by means of the DDS.Topic.get_qos operation.
  • Retrieve the default DDS.DataReader qos by means of the DDS.Subscriber.get_default_datareader_qos operation.
  • Combine those two QoS policies (for example, using DDS.Subscriber.copy_from_topic_qos) and selectively modify policies as desired
  • Use the resulting QoS policies to construct the DDS.DataReader.

    When a DDS.DataReader is created, only those transports already registered are available to the DDS.DataReader. See NDDS_TransportBuiltinsComponent for details on when a builtin transport is registered.

    MT Safety:
    UNSAFE. If DDS.DATAREADER_QOS_DEFAULT is used for the qos parameter, it is not safe to create the datareader while another thread may be simultaneously calling DDS.Subscriber.set_default_datareader_qos.

    Precondition: If subscriber is enabled, the topic must be enabled. If it is not, this operation will fail and no DDS.DataReader will be created.

    Precondition: The given DDS.TopicDescription must have been created from the same participant as this subscriber. If it was created from a different participant, this procedure will return NULL.

    Precondition: If qos is DDS.DATAREADER_QOS_USE_TOPIC_QOS, topic cannot be DDS.MultiTopic, or else this procedure will return NULL.

    self: <<in>> Cannot be NULL

    topic: <<in>> The DDS.TopicDescription that the DDS.DataReader will be associated with. Cannot be NULL.

    qos: <<in>> The qos of the DDS.DataReader. The special value DDS.DATAREADER_QOS_DEFAULT can be used to indicate that the DDS.DataReader should be created with the default DDS.DataReaderQos set in the DDS.Subscriber. If DDS.TopicDescription is of type DDS.Topic or DDS.ContentFilteredTopic, the special value DDS.DATAREADER_QOS_USE_TOPIC_QOS can be used to indicate that the DDS.DataReader should be created with the combination of the default DDS.DataReaderQos set on the DDS.Subscriber and the DDS.TopicQos (in the case of a DDS.ContentFilteredTopic, the DDS.TopicQos of the related DDS.Topic). if DDS.DATAREADER_QOS_USE_TOPIC_QOS is used, topic cannot be a DDS.MultiTopic. Cannot be NULL.

    listener: <<in>> The listener of the DDS.DataReader.

    mask: <<in>>. Changes of communication status to be invoked on the listener. See DDS.StatusMask.

    Returns: A DDS.DataReader of a derived class specific to the data-type associated with the DDS.Topic or NULL if an error occurred.


    See also: FooDataReader
    See also: DDSQosTypesModule_usage for information on setting QoS before entity creation
    See also: DDS.DataReaderQos for rules on consistency among QoS
    See also: DDS.Subscriber.create_datareader_with_profile
    See also: DDS.Subscriber.get_default_datareader_qos
    See also: DDS.Topic.set_qos
    See also: DDS.Subscriber.copy_from_topic_qos
    See also: DDS.DataReader.set_listener

    • Create_DataReader_With_Profile (abstract) 

    function Create_DataReader_With_Profile 
    (Self: not null access Ref;
    Topic: not null access DDS.TopicDescription.Ref'Class;
    Library_Name: in DDS.String;
    profile_name: in DDS.String;
    A_Listener: in DDS.DataReaderListener.Ref_Access := null;
    Mask: in DDS.StatusMask := STATUS_MASK_NONE) return DDS.DataReader.Ref_Access is abstract;

    Create_DataReader_With_Profile (abstract) 

    function Create_DataReader_With_Profile 
    (Self: not null access Ref;
    Topic: not null access DDS.TopicDescription.Ref'Class;
    Library_Name: in Standard.String;
    profile_name: in Standard.String;
    A_Listener: in DDS.DataReaderListener.Ref_Access := null;
    Mask: in DDS.StatusMask := STATUS_MASK_NONE) return DDS.DataReader.Ref_Access is abstract;

    Summary: <<ext>> Creates a DDS.DataReader object using the DDS.DataReaderQos associated with the input XML QoS profile.

    The DDS.DataReader will be attached and belong to the DDS.Subscriber.

    For each application-defined type Foo, there is an implied, auto-generated class FooDataReader (an incarnation of FooDataReader) that extends DDS.DataReader and contains the operations to read data of type Foo.

    When a DDS.DataReader is created, only those transports already registered are available to the DDS.DataReader. See NDDS_TransportBuiltinsComponent for details on when a builtin transport is registered.

    Precondition: If subscriber is enabled, the topic must be enabled. If it is not, this operation will fail and no DDS.DataReader will be created.

    Precondition: The given DDS.TopicDescription must have been created from the same participant as this subscriber. If it was created from a different participant, this procedure will return NULL.

    self: <<in>> Cannot be NULL

    topic: <<in>> The DDS.TopicDescription that the DDS.DataReader will be associated with. 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).

    listener: <<in>> The listener of the DDS.DataReader.

    mask: <<in>>. Changes of communication status to be invoked on the listener. See DDS.StatusMask.

    Returns: A DDS.DataReader of a derived class specific to the data-type associated with the DDS.Topic or NULL if an error occurred.


    See also: FooDataReader
    See also: DDSQosTypesModule_usage for information on setting QoS before entity creation
    See also: DDS.DataReaderQos for rules on consistency among QoS
    See also: DDS.DATAREADER_QOS_DEFAULT
    See also: DDS.DATAREADER_QOS_USE_TOPIC_QOS
    See also: DDS.Subscriber.create_datareader
    See also: DDS.Subscriber.get_default_datareader_qos
    See also: DDS.Topic.set_qos
    See also: DDS.Subscriber.copy_from_topic_qos
    See also: DDS.DataReader.set_listener

    Delete_DataReader (abstract) 

    procedure Delete_DataReader 
    (Self: not null access Ref;
    A_DataReader: in out DDS.DataReader.Ref_Access) is abstract;

    Summary: Deletes a DDS.DataReader that belongs to the DDS.Subscriber.

    Precondition: If the DDS.DataReader does not belong to the DDS.Subscriber, or if ther are any existing DDS.ReadCondition or DDS.QueryCondition objects that are attached to the DDS.DataReader, or if there are outstanding loans on samples (as a result of a call to read(), take(), or one of the variants thereof), the operation fails with the error DDS.RETCODE_PRECONDITION_NOT_MET.

    Postcondition: Listener installed on the DDS.DataReader will not be called after this procedure completes successfully.

    @mtsafety_delete

    self: <<in>> Cannot be NULL

    a_datareader: <<in>> The DDS.DataReader 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" operation on the DDS.Subscriber.

    Deletes all contained DDS.DataReader objects. This pattern is applied recursively. In this manner, the operation DDS.Subscriber.delete_contained_entities on the DDS.Subscriber will end up deleting all the entities recursively contained in the DDS.Subscriber, that is also the DDS.QueryCondition and DDS.ReadCondition objects belonging to the contained DDS.DataReader.

    The operation will fail with DDS.RETCODE_PRECONDITION_NOT_MET if any of the contained entities is in a state where it cannot be deleted. This will occur, for example, if a contained DDS.DataReader cannot be deleted because the application has called a FooDataReader.read or FooDataReader.take operation and has not called the corresponding FooDataReader.return_loan operation to return the loaned samples.

    Once DDS.Subscriber.delete_contained_entities completes successfully, the application may delete the DDS.Subscriber, knowing that it has no contained DDS.DataReader objects.

    @mtsafety_delete

    self: <<in>> Cannot be NULL

    Raises: One of the DDSReturnTypesModules_std_retcodes, or DDS.RETCODE_PRECONDITION_NOT_MET

    Lookup_DataReader (abstract) 

    function Lookup_DataReader 
    (Self: not null access Ref;
    Topic_Name: in DDS.String) return DDS.DataReader.Ref_Access is abstract;

    Summary: Retrieves an existing DDS.DataReader.

    Use this operation on the built-in DDS.Subscriber (DDSBuiltInTopicModule) to access the built-in DDS.DataReader entities for the built-in topics.

    The built-in DDS.DataReader is created when this operation is called on a built-in topic for the first time. The built-in DDS.DataReader is deleted automatically when the DDS.DomainParticipant is deleted.

    To ensure that builtin DDS.DataReader entities receive all the discovery traffic, it is suggested that you lookup the builtin DDS.DataReader before the DDS.DomainParticipant is enabled. Looking up builtin DDS.DataReader may implicitly register builtin transports due to creation of DDS.DataReader (see NDDS_TransportBuiltinsComponent for details on when a builtin transport is registered). Therefore, if you are want to modify builtin transport properties, do so before using this operation.

    Therefore the suggested sequence when looking up builtin DataReaders is:

  • Create a disabled DDS.DomainParticipant.
  • (optional) Modify builtin transport properties
  • Call DDS.DomainParticipant.get_builtin_subscriber().
  • Call lookup_datareader().
  • Call enable() on the DomainParticipant.

    self: <<in>> Cannot be NULL

    topic_name: <<in>> Name of the DDS.TopicDescription that the retrieved DDS.DataReader is attached to. Cannot be NULL.

    Returns: A DDS.DataReader that belongs to the DDS.Subscriber attached to the DDS.TopicDescription with topic_name. If no such DDS.DataReader exists, this operation returns NULL.

    The returned DDS.DataReader may be enabled or disabled.

    If more than one DDS.DataReader is attached to the DDS.Subscriber, this operation may return any one of them.

    MT Safety:
    UNSAFE. It is not safe to lookup a DDS.DataReader in one thread while another thread is simultaneously creating or destroying that DDS.DataReader.

    • Get_DataReaders (abstract) 

    procedure Get_DataReaders 
    (Self: not null access Ref;
    Readers: not null access DDS.DataReaderSeq.Sequence;
    Sample_States: in DDS.SampleStateKind;
    View_States: in DDS.ViewStateKind;
    Instance_States: in DDS.InstanceStateKind) is abstract;

    Summary: Allows the application to access the DDS.DataReader objects that contain samples with the specified sample_states, view_states and instance_states.

    If the application is outside a begin_access()/end_access() block, or if the DDS.PresentationQosPolicy::access_scope of the DDS.Subscriber is DDS.INSTANCE_PRESENTATION_QOS or DDS.TOPIC_PRESENTATION_QOS, or if the DDS.PresentationQosPolicy.ordered_access of the DDS.Subscriber is DDS.BOOLEAN_FALSE, the returned collection is a 'set' containing each DDS.DataReader at most once, in no specified order.

    If the application is within a begin_access()/end_access() block, and the DDSPresentationQosModule policy of the DDS.Subscriber is DDS.GROUP_PRESENTATION_QOS or DDS.HIGHEST_OFFERED_PRESENTATION_QOS, and DDS.PresentationQosPolicy.ordered_access in the DDS.Subscriber is DDS.BOOLEAN_TRUE, the returned collection is a 'list' of DataReaders where a DataReader may appear more than one time.

    To retrieve the samples in the order they were published across DataWriters of the same group (DDS.Publisher configured with DDS.GROUP_PRESENTATION_QOS), the application should read()/take() from each DataReader in the same order as it appears in the output sequence. The application will move to the next DataReader when the read()/take() operation fails with DDS.RETCODE_NO_DATA.

    self: <<in>> Cannot be NULL

    readers: <<inout>> a DDSDataReaderSeq object where the set or list of readers will be returned. Cannot be NULL.

    sample_states: <<in>> the returned DataReader must contain samples that have one of these sample_states.

    view_states: <<in>> the returned DataReader must contain samples that have one of these view_states.

    instance_states: <<in>> the returned DataReader must contain samples that have one of these instance_states.

    Raises: One of the DDSReturnTypesModules_std_retcodes or DDS.RETCODE_NOT_ENABLED.
    See also: Subscription_access_samples
    See also: DDS.Subscriber.begin_access
    See also: DDS.Subscriber.end_access
    See also: DDSPresentationQosModule

    Notify_DataReaders (abstract) 

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

    Summary: Invokes the operation DDS.DataReaderListener::on_data_available() on the DDS.DataReaderListener objects attached to contained DDS.DataReader entities with DDS.DATA_AVAILABLE_STATUS that is considered changed as described in Status_changes_read.

    This operation is typically invoked from the DDS.SubscriberListener.on_data_on_readers operation in the DDS.SubscriberListener. That way the DDS.SubscriberListener can delegate to the DDS.DataReaderListener objects the handling of the data.

    The operation will notify the data readers that have a sample_state of DDS.NOT_READ_SAMPLE_STATE, view_state of DDS.ANY_SAMPLE_STATE and instance_state of DDS.ANY_INSTANCE_STATE.

    self: <<in>> Cannot be NULL

    Raises: One of the DDSReturnTypesModules_std_retcodes, or DDS.RETCODE_NOT_ENABLED.

    Set_Qos (abstract) 

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

    Summary: Sets the subscriber QoS.

    This operation modifies the QoS of the DDS.Subscriber.

    The DDS.SubscriberQos.group_data, DDS.SubscriberQos.partition and DDS.SubscriberQos.entity_factory can be changed. The other policies are immutable.

    self: <<in>> Cannot be NULL

    qos: <<in>> DDS.SubscriberQos to be set to. Policies must be consistent. Immutable policies cannot be changed after DDS.Subscriber is enabled. The special value DDS.SUBSCRIBER_QOS_DEFAULT can be used to indicate that the QoS of the DDS.Subscriber should be changed to match the current default DDS.SubscriberQos set in the DDS.DomainParticipant. Cannot be NULL.

    Raises: One of the DDSReturnTypesModules_std_retcodes, DDS.RETCODE_IMMUTABLE_POLICY, or DDS.RETCODE_INCONSISTENT_POLICY.


    See also: DDS.SubscriberQos for rules on consistency among QoS
    See also: Entity_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>> Change the QoS of this subscriber using the input XML QoS profile.

    This operation modifies the QoS of the DDS.Subscriber.

    The DDS.SubscriberQos.group_data, DDS.SubscriberQos.partition and DDS.SubscriberQos.entity_factory 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.SubscriberQos for rules on consistency among QoS
    See also: SharedEACallbackRules

    Get_Qos (abstract) 

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

    Summary: Gets the subscriber QoS.

    This procedure may potentially allocate memory depending on the sequences contained in some QoS policies.

    self: <<in>> Cannot be NULL

    qos: <<in>> DDS.SubscriberQos to be filled in. 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: DDS.SubscriberListener.Ref_Access;
    Mask: in       DDS.StatusKind) is abstract;

    Summary: Sets the subscriber listener.

    self: <<in>> Cannot be NULL

    l: <<in>> DDS.SubscriberListener to set to.

    mask: <<in>> DDS.StatusMask associated with the DDS.SubscriberListener.

    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.SubscriberListener.Ref_Access is abstract;

    Summary: Get the subscriber listener.

    self: <<in>> Cannot be NULL

    Returns: DDS.SubscriberListener of the DDS.Subscriber.


    See also: Entity_get_listener

    Begin_Access (abstract) 

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

    Summary: Indicates that the application is about to access the data samples in any of the DDS.DataReader objects attached to the DDS.Subscriber.

    If the DDS.PresentationQosPolicy::access_scope of the DDS.Subscriber is DDS.GROUP_PRESENTATION_QOS or DDS.HIGHEST_OFFERED_PRESENTATION_QOS and DDS.PresentationQosPolicy::ordered_access is DDS.BOOLEAN_TRUE, the application is required to use this operation to access the samples in order across DataWriters of the same group (DDS.Publisher with DDS.PresentationQosPolicy.access_scope set to DDS.GROUP_PRESENTATION_QOS).

    In the above case, this operation must be called prior to calling any of the sample-accessing operations,

    Once the application has finished accessing the data samples, it must call DDS.Subscriber.end_access

    The application is not required to call DDS.Subscriber.begin_access / DDS.Subscriber.end_access to access the samples in order if the DDSPresentationQosModule policy in the DDS.Publisher has DDS.PresentationQosPolicy.access_scope set to something other than DDS.GROUP_PRESENTATION_QOS. In this case, calling DDS.Subscriber.begin_access / DDS.Subscriber.end_access is not considered an error and has no effect.

    Calls to DDS.Subscriber.begin_access / DDS.Subscriber.end_access may be nested and must be balanced.

    self: <<in>> Cannot be NULL

    Raises: One of the DDSReturnTypesModules_std_retcodes or DDS.RETCODE_NOT_ENABLED.


    See also: Subscription_access_samples
    See also: DDS.Subscriber.get_datareaders
    See also: DDSPresentationQosModule

    End_Access (abstract) 

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

    Summary: Indicates that the application has finished accessing the data samples in DDS.DataReader objects managed by the DDS.Subscriber.

    This operation must be used to close a corresponding begin_access().

    This call must close a previous call to DDS.Subscriber.begin_access(), otherwise the operation will fail with the error DDS.RETCODE_PRECONDITION_NOT_MET.

    self: <<in>> Cannot be NULL

    Raises: One of the DDSReturnTypesModules_std_retcodes or DDS.RETCODE_PRECONDITION_NOT_MET or DDS.RETCODE_NOT_ENABLED.

    Get_Participant (abstract) 

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

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

    self: <<in>> Cannot be NULL

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

    Set_Default_DataReader_Qos (abstract) 

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

    Summary: Sets the default DDS.DataReaderQos values for this subscriber.

    This call causes the default values inherited from the owning DDS.DomainParticipant to be overridden.

    This default value will be used for newly created DDS.DataReader if DDS.DATAREADER_QOS_DEFAULT is specified as the qos parameter when DDS.Subscriber.create_datareader is called.

    Precondition: The specified QoS policies must be consistent, or else the operation will have no effect and fail with DDS.RETCODE_INCONSISTENT_POLICY

    MT Safety:
    UNSAFE. It is not safe to set the default QoS value from a subscriber while another thread may be simultaneously calling DDS.Subscriber.set_default_datareader_qos, DDS.Subscriber.get_default_datareader_qos or calling DDS.Subscriber.create_datareader with DDS.DATAREADER_QOS_DEFAULT as the qos parameter.

    self: <<in>> Cannot be NULL

    qos: <<in>> The default DDS.DataReaderQos to be set to. The special value DDS.DATAREADER_QOS_DEFAULT may be passed as qos to indicate that the default QoS should be reset back to the initial values the factory would used if DDS.Subscriber.set_default_datareader_qos had never been called. Cannot be NULL.

    Raises: One of the DDSReturnTypesModules_std_retcodes, or or DDS.RETCODE_INCONSISTENT_POLICY

    Set_Default_DataReader_Qos_With_Profile (abstract) 

    procedure Set_Default_DataReader_Qos_With_Profile 
    (Self: not null access Ref;
    libName: DDS.String;
    profName: DDS.String) is abstract;

    Set_Default_DataReader_Qos_With_Profile (abstract) 

    procedure Set_Default_DataReader_Qos_With_Profile 
    (Self: not null access Ref;
    libName: Standard.String;
    profName: Standard.String) is abstract;

    Summary: <<ext>> Set the default DDS.DataReaderQos values for this subscriber based on the input XML QoS profile.

    This default value will be used for newly created DDS.DataReader if DDS.DATAREADER_QOS_DEFAULT is specified as the qos parameter when DDS.Subscriber.create_datareader is called.

    Precondition: The DDS.DataReaderQos contained in the specified XML QoS profile must be consistent, or else the operation will have no effect and fail with DDS.RETCODE_INCONSISTENT_POLICY

    MT Safety:
    UNSAFE. It is not safe to set the default QoS value from a DDS.Subscriber while another thread may be simultaneously calling DDS.Subscriber.set_default_datareader_qos, DDS.Subscriber.get_default_datareader_qos or calling DDS.Subscriber.create_datareader with DDS.DATAREADER_QOS_DEFAULT as the qos parameter.

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

    If the input profile cannot be found the procedure fails with DDS.RETCODE_ERROR.

    Raises: One of the DDSReturnTypesModules_std_retcodes, or DDS.RETCODE_INCONSISTENT_POLICY


    See also: DDS.DATAREADER_QOS_DEFAULT
    See also: DDS.Subscriber.create_datareader_with_profile

    Get_Default_DataReader_Qos (abstract) 

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

    Summary: Copies the default DDS.DataReaderQos values into the provided DDS.DataReaderQos instance.

    The retrieved qos will match the set of values specified on the last successful call to DDS.Subscriber.set_default_datareader_qos, or DDS.Subscriber.set_default_datareader_qos_with_profile, or else, if the call was never made, the default values from is owning DDS.DomainParticipant.

    This procedure may potentially allocate memory depending on the sequences contained in some QoS policies.

    MT Safety:
    UNSAFE. It is not safe to retrieve the default QoS value from a subscriber while another thread may be simultaneously calling DDS.Subscriber.set_default_datareader_qos

    self: <<in>> Cannot be NULL

    qos: <<inout>> DDS.DataReaderQos to be filled-up. Cannot be NULL.

    Raises: One of the DDSReturnTypesModules_std_retcodes


    See also: DDS.DATAREADER_QOS_DEFAULT
    See also: DDS.Subscriber.create_datareader

    Copy_From_Topic_Qos (abstract) 

    procedure Copy_From_Topic_Qos 
    (Self: not null access Ref;
    A_DataReader_Qos: in out DDS.DataReaderQoS;
    A_Topic_Qos: in DDS.TopicQos) is abstract;

    Summary: Copies the policies in the DDS.TopicQos to the corresponding policies in the DDS.DataReaderQos

    Copies the policies in the DDS.TopicQos to the corresponding policies in the DDS.DataReaderQos (replacing values in the DDS.DataReaderQos, if present).

    This is a "convenience" operation most useful in combination with the operations DDS.Subscriber.get_default_datareader_qos and DDS.Topic.get_qos. The operation DDS.Subscriber.copy_from_topic_qos can be used to merge the DDS.DataReader default QoS policies with the corresponding ones on the DDS.Topic. The resulting QoS can then be used to create a new DDS.DataReader, or set its QoS.

    This operation does not check the resulting DDS.DataReaderQos for consistency. This is because the 'merged' DDS.DataReaderQos may not be the final one, as the application can still modify some policies prior to applying the policies to the DDS.DataReader.

    self: <<in>> Cannot be NULL

    datareader_qos: <<inout>> DDS.DataReaderQos to be filled-up. Cannot be NULL.

    topic_qos: <<in>> DDS.TopicQos to be merged with DDS.DataReaderQos. Cannot be NULL.

    Raises: One of the DDSReturnTypesModules_std_retcodes

    Set_Default_Profile (abstract) 

    procedure Set_Default_Profile 
    (Self: not null access Ref;
    library_name: DDS.String;
    profile_name: DDS.String) is abstract;

    Summary: <<ext>> Sets the default XML profile for a DDS.Subscriber.

    This procedure specifies the profile that will be used as the default the next time a default Subscriber profile is needed during a call to one of this Subscriber's operations. When calling a DDS.Subscriber procedure that requires a profile_name parameter, you can use NULL to refer to the default profile. (This same information applies to setting a default library.)

    If the default profile is not set, the DDS.Subscriber inherits the default from the DDS.DomainParticipant (see DDS.DomainParticipant.set_default_profile).

    This procedure does not set the default QoS for DDS.DataReader objects created by this DDS.Subscriber; for this functionality, use DDS.Subscriber.set_default_datareader_qos_with_profile (you may pass in NULL after having called set_default_profile()).

    This procedure does not set the default QoS for newly created Subscribers; for this functionality, use DDS.DomainParticipant.set_default_subscriber_qos_with_profile.

    self: <<in>> Cannot be NULL

    library_name: <<in>> The library name containing the profile.

    profile_name: <<in>> The profile name. If profile_name is null any previous default is unset.

    Raises: One of the DDSReturnTypesModules_std_retcodes


    See also: DDS.Subscriber.get_default_profile
    See also: DDS.Subscriber.get_default_profile_library

    Set_Default_Library (abstract) 

    procedure Set_Default_Library 
    (Self: not null access Ref;
    library_name: DDS.String) is abstract;

    Summary: <<ext>> Sets the default XML library for a DDS.Subscriber.

    This procedure specifies the library that will be used as the default the next time a default library is needed during a call to one of this Subscriber's operations.

    Any API requiring a library_name as a parameter can use null to refer to the default library.

    If the default library is not set, the DDS.Subscriber inherits the default from the DDS.DomainParticipant (see DDS.DomainParticipant.set_default_library).

    self: <<in>> Cannot be NULL

    library_name: <<in>> Library name. If library_name is null any previous default is unset.

    Raises: One of the DDSReturnTypesModules_std_retcodes


    See also: DDS.Subscriber.get_default_library

    Get_Default_Library (abstract) 

    function Get_Default_Library 
    (Self: not null access Ref) return DDS.String is abstract;

    Summary: <<ext>> Gets the default XML library associated with a DDS.Subscriber.

    self: <<in>> Cannot be NULL

    Returns: The default library or null if the default library was not set.


    See also: DDS.Subscriber.set_default_library

    Get_Default_Profile (abstract) 

    function Get_Default_Profile 
    (Self: not null access Ref) return DDS.String is abstract;

    Summary: <<ext>> Gets the default XML profile associated with a DDS.Subscriber.

    self: <<in>> Cannot be NULL

    Returns: The default profile or null if the default profile was not set.


    See also: DDS.Subscriber.set_default_profile

    Get_Default_Profile_Library (abstract) 

    function Get_Default_Profile_Library 
    (Self: not null access Ref) return DDS.String is abstract;

    Summary: <<ext>> Gets the library where the default XML QoS profile is contained for a DDS.Subscriber.

    The default profile library is automatically set when DDS.Subscriber.set_default_profile is called.

    This library can be different than the DDS.Subscriber default library (see DDS.Subscriber.get_default_library).

    self: <<in>> Cannot be NULL

    Returns: The default profile library or null if the default profile was not set.


    See also: DDS.Subscriber.set_default_profile