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

Inheritance diagram for Subscriber:

Public Member Functions
void	get_default_datareader_qos (DataReaderQos qos)
	Copies the default com.rti.dds.subscription.DataReaderQos values into the provided com.rti.dds.subscription.DataReaderQos instance.

void	set_default_datareader_qos (DataReaderQos qos)
	Sets the default com.rti.dds.subscription.DataReaderQos values for this subscriber.

void	set_default_datareader_qos_with_profile (String library_name, String profile_name)
	<<eXtension>> Set the default com.rti.dds.subscription.DataReaderQos values for this subscriber based on the input XML QoS profile.

DataReader	create_datareader (TopicDescription topic, DataReaderQos qos, DataReaderListener listener, int mask)
	Creates a com.rti.dds.subscription.DataReader that will be attached and belong to the com.rti.dds.subscription.Subscriber.

DataReader	create_datareader_with_profile (TopicDescription topic, String library_name, String profile_name, DataReaderListener listener, int mask)
	<<eXtension>> Creates a com.rti.dds.subscription.DataReader object using the com.rti.dds.subscription.DataReaderQos associated with the input XML QoS profile.

void	delete_datareader (DataReader a_datareader)
	Deletes a com.rti.dds.subscription.DataReader that belongs to the com.rti.dds.subscription.Subscriber.

DataReader	lookup_datareader (String topic_name)
	Retrieves an existing com.rti.dds.subscription.DataReader.

void	get_datareaders (DataReaderSeq readers, int sample_states, int view_states, int instance_states)
	Allows the application to access the com.rti.dds.subscription.DataReader objects that contain samples with the specified `sample_states`, `view_states` and `instance_states`.

void	get_all_datareaders (DataReaderSeq readers)
	Retrieve all the DataReaders created from this Subscriber.

void	notify_datareaders ()
	Invokes the operation com.rti.dds.subscription.DataReaderListener::on_data_available() on the com.rti.dds.subscription.DataReaderListener objects attached to contained com.rti.dds.subscription.DataReader entities with com.rti.dds.infrastructure.StatusKind.StatusKind.DATA_AVAILABLE_STATUS that is considered changed as described in Changes in read communication status.

void	set_qos (SubscriberQos qos)
	Sets the subscriber QoS.

void	set_qos_with_profile (String library_name, String profile_name)
	<<eXtension>> Change the QoS of this subscriber using the input XML QoS profile.

void	get_qos (SubscriberQos qos)
	Gets the subscriber QoS.

String	get_default_library ()
	<<eXtension>> Gets the default XML library associated with a com.rti.dds.subscription.Subscriber.

void	set_default_library (String library_name)
	<<eXtension>> Sets the default XML library for a com.rti.dds.subscription.Subscriber.

String	get_default_profile ()
	<<eXtension>> Gets the default XML profile associated with a com.rti.dds.subscription.Subscriber.

void	set_default_profile (String library_name, String profile_name)
	<<eXtension>> Sets the default XML profile for a com.rti.dds.subscription.Subscriber.

String	get_default_profile_library ()
	<<eXtension>> Gets the library where the default XML QoS profile is contained for a com.rti.dds.subscription.Subscriber.

void	set_listener (SubscriberListener l, int mask)
	Sets the subscriber listener.

SubscriberListener	get_listener ()
	Get the subscriber listener.

void	call_listenerT (int mask)
	Call the subscriber listener.

void	begin_access ()
	Indicates that the application is about to access the data samples in any of the com.rti.dds.subscription.DataReader objects attached to the com.rti.dds.subscription.Subscriber.

void	end_access ()
	Indicates that the application has finished accessing the data samples in com.rti.dds.subscription.DataReader objects managed by the com.rti.dds.subscription.Subscriber.

void	copy_from_topic_qos (DataReaderQos datareader_qos, TopicQos topic_qos)
	Copies the policies in the com.rti.dds.topic.TopicQos to the corresponding policies in the com.rti.dds.subscription.DataReaderQos.

DomainParticipant	get_participant ()
	Returns the com.rti.dds.domain.DomainParticipant to which the com.rti.dds.subscription.Subscriber belongs.

void	delete_contained_entities ()
	Deletes all the entities that were created by means of the "create" operation on the com.rti.dds.subscription.Subscriber.

DataReader	lookup_datareader_by_name_exp (String datareader_name)
	<<experimental>> <<eXtension>> Retrieves a com.rti.dds.subscription.DataReader contained within the com.rti.dds.subscription.Subscriber the com.rti.dds.subscription.DataReader entity name.

Static Public Attributes
static final DataReaderQos	DATAREADER_QOS_DEFAULT
	Special value for creating data reader with default QoS.

static final DataReaderQos	DATAREADER_QOS_USE_TOPIC_QOS = new DataReaderQos()
	Special value for creating com.rti.dds.subscription.DataReader with a combination of the default com.rti.dds.subscription.DataReaderQos and the com.rti.dds.topic.TopicQos.

Detailed Description

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

QoS:: com.rti.dds.subscription.SubscriberQos

Status:: com.rti.dds.infrastructure.StatusKind.StatusKind.DATA_ON_READERS_STATUS

Listener:: com.rti.dds.subscription.SubscriberListener

A subscriber acts on the behalf of one or several com.rti.dds.subscription.DataReader objects that are related to it. When it receives data (from the other parts of the system), it builds the list of concerned com.rti.dds.subscription.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 com.rti.dds.subscription.DataReader objects through the operation get_datareaders() and then access the data available through operations on the com.rti.dds.subscription.DataReader.

The following operations may be called even if the com.rti.dds.subscription.Subscriber is not enabled. Other operations will the value com.rti.dds.infrastructure.RETCODE_NOT_ENABLED if called on a disabled com.rti.dds.subscription.Subscriber:

All operations except for the base-class operations set_qos(), set_qos_with_profile(), get_qos(), set_listener(), get_listener(), enable() and create_datareader() may fail with com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

See Also: Operations Allowed in Listener Callbacks

Member Function Documentation

void get_default_datareader_qos ( DataReaderQos qos )

Copies the default com.rti.dds.subscription.DataReaderQos values into the provided com.rti.dds.subscription.DataReaderQos instance.

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

This method 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 com.rti.dds.subscription.Subscriber.set_default_datareader_qos

Parameters

qos	<<inout>> com.rti.dds.subscription.DataReaderQos to be filled-up. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

See Also: com.rti.dds.subscription.Subscriber.DATAREADER_QOS_DEFAULT; com.rti.dds.subscription.Subscriber.create_datareader

void set_default_datareader_qos ( DataReaderQos qos )

Sets the default com.rti.dds.subscription.DataReaderQos values for this subscriber.

This call causes the default values inherited from the owning com.rti.dds.domain.DomainParticipant to be overridden.

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

Precondition: The specified QoS policies must be consistent, or else the operation will have no effect and fail with com.rti.dds.infrastructure.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 com.rti.dds.subscription.Subscriber.set_default_datareader_qos, com.rti.dds.subscription.Subscriber.get_default_datareader_qos or calling com.rti.dds.subscription.Subscriber.create_datareader with com.rti.dds.subscription.Subscriber.DATAREADER_QOS_DEFAULT as the qos parameter.

Parameters

qos <<in>> The default com.rti.dds.subscription.DataReaderQos to be set to. The special value com.rti.dds.subscription.Subscriber.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 com.rti.dds.subscription.Subscriber.set_default_datareader_qos had never been called. Cannot be NULL.

Exceptions

One	of the Standard Return Codes, or or com.rti.dds.infrastructure.RETCODE_INCONSISTENT_POLICY

void set_default_datareader_qos_with_profile	(	String	library_name,
		String	profile_name
	)

<<eXtension>> Set the default com.rti.dds.subscription.DataReaderQos values for this subscriber based on the input XML QoS profile.

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

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

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

Parameters

library_name	<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see com.rti.dds.subscription.Subscriber.set_default_library).
profile_name	<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see com.rti.dds.subscription.Subscriber.set_default_profile).

If the input profile cannot be found the method fails with com.rti.dds.infrastructure.RETCODE_ERROR.

Exceptions

One	of the Standard Return Codes, or com.rti.dds.infrastructure.RETCODE_INCONSISTENT_POLICY

See Also: com.rti.dds.subscription.Subscriber.DATAREADER_QOS_DEFAULT; com.rti.dds.subscription.Subscriber.create_datareader_with_profile

DataReader create_datareader	(	TopicDescription	topic,
		DataReaderQos	qos,
		DataReaderListener	listener,
		int	mask
	)

Creates a com.rti.dds.subscription.DataReader that will be attached and belong to the com.rti.dds.subscription.Subscriber.

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

Note that a common application pattern to construct the QoS for the com.rti.dds.subscription.DataReader is to:

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

When a com.rti.dds.subscription.DataReader is created, only those transports already registered are available to the com.rti.dds.subscription.DataReader. See Built-in Transport Plugins for details on when a builtin transport is registered.

MT Safety:: UNSAFE. If com.rti.dds.subscription.Subscriber.DATAREADER_QOS_DEFAULT is used for the qos parameter, it is not safe to create the datareader while another thread may be simultaneously calling com.rti.dds.subscription.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 com.rti.dds.subscription.DataReader will be created.; The given com.rti.dds.topic.TopicDescription must have been created from the same participant as this subscriber. If it was created from a different participant, this method will return NULL.; If qos is com.rti.dds.subscription.Subscriber.DATAREADER_QOS_USE_TOPIC_QOS, topic cannot be com.rti.dds.topic.MultiTopic, or else this method will return NULL.

Parameters

topic	<<in>> The com.rti.dds.topic.TopicDescription that the com.rti.dds.subscription.DataReader will be associated with. Cannot be NULL.
qos	<<in>> The qos of the com.rti.dds.subscription.DataReader. The special value com.rti.dds.subscription.Subscriber.DATAREADER_QOS_DEFAULT can be used to indicate that the com.rti.dds.subscription.DataReader should be created with the default com.rti.dds.subscription.DataReaderQos set in the com.rti.dds.subscription.Subscriber. If com.rti.dds.topic.TopicDescription is of type com.rti.dds.topic.Topic or com.rti.dds.topic.ContentFilteredTopic, the special value com.rti.dds.subscription.Subscriber.DATAREADER_QOS_USE_TOPIC_QOS can be used to indicate that the com.rti.dds.subscription.DataReader should be created with the combination of the default com.rti.dds.subscription.DataReaderQos set on the com.rti.dds.subscription.Subscriber and the com.rti.dds.topic.TopicQos (in the case of a com.rti.dds.topic.ContentFilteredTopic, the com.rti.dds.topic.TopicQos of the related com.rti.dds.topic.Topic). if com.rti.dds.subscription.Subscriber.DATAREADER_QOS_USE_TOPIC_QOS is used, `topic` cannot be a com.rti.dds.topic.MultiTopic. Cannot be NULL.
listener	<<in>> The listener of the com.rti.dds.subscription.DataReader.
mask	<<in>>. Changes of communication status to be invoked on the listener. See com.rti.dds.infrastructure.StatusMask.

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

See Also: com.rti.ndds.example.FooDataReader; Specifying QoS on entities for information on setting QoS before entity creation; com.rti.dds.subscription.DataReaderQos for rules on consistency among QoS; com.rti.dds.subscription.Subscriber.create_datareader_with_profile; com.rti.dds.subscription.Subscriber.get_default_datareader_qos; com.rti.dds.topic.Topic.set_qos; com.rti.dds.subscription.Subscriber.copy_from_topic_qos; com.rti.dds.subscription.DataReader.set_listener

DataReader create_datareader_with_profile	(	TopicDescription	topic,
		String	library_name,
		String	profile_name,
		DataReaderListener	listener,
		int	mask
	)

<<eXtension>> Creates a com.rti.dds.subscription.DataReader object using the com.rti.dds.subscription.DataReaderQos associated with the input XML QoS profile.

The com.rti.dds.subscription.DataReader will be attached and belong to the com.rti.dds.subscription.Subscriber.

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

When a com.rti.dds.subscription.DataReader is created, only those transports already registered are available to the com.rti.dds.subscription.DataReader. See Built-in Transport Plugins 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 com.rti.dds.subscription.DataReader will be created.; The given com.rti.dds.topic.TopicDescription must have been created from the same participant as this subscriber. If it was created from a different participant, this method will return NULL.

Parameters

topic	<<in>> The com.rti.dds.topic.TopicDescription that the com.rti.dds.subscription.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 com.rti.dds.subscription.Subscriber.set_default_library).
profile_name	<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see com.rti.dds.subscription.Subscriber.set_default_profile).
listener	<<in>> The listener of the com.rti.dds.subscription.DataReader.
mask	<<in>>. Changes of communication status to be invoked on the listener. See com.rti.dds.infrastructure.StatusMask.

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

See Also: com.rti.ndds.example.FooDataReader; Specifying QoS on entities for information on setting QoS before entity creation; com.rti.dds.subscription.DataReaderQos for rules on consistency among QoS; com.rti.dds.subscription.Subscriber.DATAREADER_QOS_DEFAULT; com.rti.dds.subscription.Subscriber.DATAREADER_QOS_USE_TOPIC_QOS; com.rti.dds.subscription.Subscriber.create_datareader; com.rti.dds.subscription.Subscriber.get_default_datareader_qos; com.rti.dds.topic.Topic.set_qos; com.rti.dds.subscription.Subscriber.copy_from_topic_qos; com.rti.dds.subscription.DataReader.set_listener

void delete_datareader ( DataReader a_datareader )

Deletes a com.rti.dds.subscription.DataReader that belongs to the com.rti.dds.subscription.Subscriber.

Precondition: If the com.rti.dds.subscription.DataReader does not belong to the com.rti.dds.subscription.Subscriber, or if ther are any existing com.rti.dds.subscription.ReadCondition or com.rti.dds.subscription.QueryCondition objects that are attached to the com.rti.dds.subscription.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 com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET.

Postcondition: Listener installed on the com.rti.dds.subscription.DataReader will not be called after this method completes successfully.

Parameters

a_datareader <<in>> The com.rti.dds.subscription.DataReader to be deleted.

Exceptions

One	of the Standard Return Codes or com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET.

DataReader lookup_datareader ( String topic_name )

Retrieves an existing com.rti.dds.subscription.DataReader.

Use this operation on the built-in com.rti.dds.subscription.Subscriber (Built-in Topics) to access the built-in com.rti.dds.subscription.DataReader entities for the built-in topics.

The built-in com.rti.dds.subscription.DataReader is created when this operation is called on a built-in topic for the first time. The built-in com.rti.dds.subscription.DataReader is deleted automatically when the com.rti.dds.domain.DomainParticipant is deleted.

To ensure that builtin com.rti.dds.subscription.DataReader entities receive all the discovery traffic, it is suggested that you lookup the builtin com.rti.dds.subscription.DataReader before the com.rti.dds.domain.DomainParticipant is enabled. Looking up builtin com.rti.dds.subscription.DataReader may implicitly register builtin transports due to creation of com.rti.dds.subscription.DataReader (see Built-in Transport Plugins 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 com.rti.dds.domain.DomainParticipant.
(optional) Modify builtin transport properties
Call com.rti.dds.domain.DomainParticipant.get_builtin_subscriber().
Call lookup_datareader().
Call enable() on the DomainParticipant.

Parameters

topic_name <<in>> Name of the com.rti.dds.topic.TopicDescription that the retrieved com.rti.dds.subscription.DataReader is attached to. Cannot be NULL.

Returns: A com.rti.dds.subscription.DataReader that belongs to the com.rti.dds.subscription.Subscriber attached to the com.rti.dds.topic.TopicDescription with topic_name. If no such com.rti.dds.subscription.DataReader exists, this operation returns NULL.

The returned com.rti.dds.subscription.DataReader may be enabled or disabled.

If more than one com.rti.dds.subscription.DataReader is attached to the com.rti.dds.subscription.Subscriber, this operation may return any one of them.

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

void get_datareaders	(	DataReaderSeq	readers,
		int	sample_states,
		int	view_states,
		int	instance_states
	)

Allows the application to access the com.rti.dds.subscription.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 com.rti.dds.infrastructure.PresentationQosPolicy::access_scope of the com.rti.dds.subscription.Subscriber is com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.INSTANCE_PRESENTATION_QOS or com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.TOPIC_PRESENTATION_QOS, or if the com.rti.dds.infrastructure.PresentationQosPolicy.ordered_access of the com.rti.dds.subscription.Subscriber is com.rti.dds.infrastructure.false, the returned collection is a 'set' containing each com.rti.dds.subscription.DataReader at most once, in no specified order.

If the application is within a begin_access()/end_access() block, and the PRESENTATION policy of the com.rti.dds.subscription.Subscriber is com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.GROUP_PRESENTATION_QOS or com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.HIGHEST_OFFERED_PRESENTATION_QOS, and com.rti.dds.infrastructure.PresentationQosPolicy.ordered_access in the com.rti.dds.subscription.Subscriber is com.rti.dds.infrastructure.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 (com.rti.dds.publication.Publisher configured with com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.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 com.rti.dds.infrastructure.RETCODE_NO_DATA.

Parameters

readers	<<inout>> a com.rti.dds.subscription.DataReaderSeq 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`.

Exceptions

One	of the Standard Return Codes or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

See Also: Access to data samples; com.rti.dds.subscription.Subscriber.begin_access; com.rti.dds.subscription.Subscriber.end_access; PRESENTATION

void get_all_datareaders ( DataReaderSeq readers )

Retrieve all the DataReaders created from this Subscriber.

Parameters

readers <<inout>> Sequence where the DataReaders will be added

Exceptions

One	of the Standard Return Codes

void notify_datareaders ( )

Invokes the operation com.rti.dds.subscription.DataReaderListener::on_data_available() on the com.rti.dds.subscription.DataReaderListener objects attached to contained com.rti.dds.subscription.DataReader entities with com.rti.dds.infrastructure.StatusKind.StatusKind.DATA_AVAILABLE_STATUS that is considered changed as described in Changes in read communication status.

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

The operation will notify the data readers that have a sample_state of com.rti.dds.subscription.SampleStateKind.SampleStateKind.NOT_READ_SAMPLE_STATE, view_state of com.rti.dds.subscription.SampleStateKind.ANY_SAMPLE_STATE and instance_state of com.rti.dds.subscription.InstanceStateKind.ANY_INSTANCE_STATE.

Exceptions

One	of the Standard Return Codes, or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

void set_qos ( SubscriberQos qos )

Sets the subscriber QoS.

This operation modifies the QoS of the com.rti.dds.subscription.Subscriber.

The com.rti.dds.subscription.SubscriberQos.group_data, com.rti.dds.subscription.SubscriberQos.partition and com.rti.dds.subscription.SubscriberQos.entity_factory can be changed. The other policies are immutable.

Parameters

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

Exceptions

One	of the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_IMMUTABLE_POLICY, or com.rti.dds.infrastructure.RETCODE_INCONSISTENT_POLICY.

See Also: com.rti.dds.subscription.SubscriberQos for rules on consistency among QoS; set_qos (abstract); Operations Allowed in Listener Callbacks

void set_qos_with_profile	(	String	library_name,
		String	profile_name
	)

<<eXtension>> Change the QoS of this subscriber using the input XML QoS profile.

This operation modifies the QoS of the com.rti.dds.subscription.Subscriber.

The com.rti.dds.subscription.SubscriberQos.group_data, com.rti.dds.subscription.SubscriberQos.partition and com.rti.dds.subscription.SubscriberQos.entity_factory can be changed. The other policies are immutable.

Parameters

library_name	<<in>> Library name containing the XML QoS profile. If library_name is null RTI Connext will use the default library (see com.rti.dds.subscription.Subscriber.set_default_library).
profile_name	<<in>> XML QoS Profile name. If profile_name is null RTI Connext will use the default profile (see com.rti.dds.subscription.Subscriber.set_default_profile).

Exceptions

One	of the Standard Return Codes, com.rti.dds.infrastructure.RETCODE_IMMUTABLE_POLICY, or com.rti.dds.infrastructure.RETCODE_INCONSISTENT_POLICY.

See Also: com.rti.dds.subscription.SubscriberQos for rules on consistency among QoS; Operations Allowed in Listener Callbacks

void get_qos ( SubscriberQos qos )

Gets the subscriber QoS.

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

Parameters

qos	<<in>> com.rti.dds.subscription.SubscriberQos to be filled in. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

See Also: get_qos (abstract)

String get_default_library ( )

<<eXtension>> Gets the default XML library associated with a com.rti.dds.subscription.Subscriber.

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

See Also: com.rti.dds.subscription.Subscriber.set_default_library

void set_default_library ( String library_name )

<<eXtension>> Sets the default XML library for a com.rti.dds.subscription.Subscriber.

This method 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 com.rti.dds.subscription.Subscriber inherits the default from the com.rti.dds.domain.DomainParticipant (see com.rti.dds.domain.DomainParticipant.set_default_library).

Parameters

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

Exceptions

One	of the Standard Return Codes

See Also: com.rti.dds.subscription.Subscriber.get_default_library

String get_default_profile ( )

<<eXtension>> Gets the default XML profile associated with a com.rti.dds.subscription.Subscriber.

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

See Also: com.rti.dds.subscription.Subscriber.set_default_profile

void set_default_profile	(	String	library_name,
		String	profile_name
	)

<<eXtension>> Sets the default XML profile for a com.rti.dds.subscription.Subscriber.

This method 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 com.rti.dds.subscription.Subscriber method 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 com.rti.dds.subscription.Subscriber inherits the default from the com.rti.dds.domain.DomainParticipant (see com.rti.dds.domain.DomainParticipant.set_default_profile).

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

This method does not set the default QoS for newly created Subscribers; for this functionality, use com.rti.dds.domain.DomainParticipant.set_default_subscriber_qos_with_profile.

Parameters

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.

Exceptions

One	of the Standard Return Codes

See Also: com.rti.dds.subscription.Subscriber.get_default_profile; com.rti.dds.subscription.Subscriber.get_default_profile_library

String get_default_profile_library ( )

<<eXtension>> Gets the library where the default XML QoS profile is contained for a com.rti.dds.subscription.Subscriber.

The default profile library is automatically set when com.rti.dds.subscription.Subscriber.set_default_profile is called.

This library can be different than the com.rti.dds.subscription.Subscriber default library (see com.rti.dds.subscription.Subscriber.get_default_library).

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

See Also: com.rti.dds.subscription.Subscriber.set_default_profile

void set_listener	(	SubscriberListener	l,
		int	mask
	)

Sets the subscriber listener.

Parameters

l	<<in>> com.rti.dds.subscription.SubscriberListener to set to.
mask	<<in>> com.rti.dds.infrastructure.StatusMask associated with the com.rti.dds.subscription.SubscriberListener.

Exceptions

One	of the Standard Return Codes

See Also: set_listener (abstract)

SubscriberListener get_listener ( )

Get the subscriber listener.

Returns: com.rti.dds.subscription.SubscriberListener of the com.rti.dds.subscription.Subscriber.

See Also: get_listener (abstract)

void call_listenerT ( int mask )

Call the subscriber listener.

void begin_access ( )

Indicates that the application is about to access the data samples in any of the com.rti.dds.subscription.DataReader objects attached to the com.rti.dds.subscription.Subscriber.

If the com.rti.dds.infrastructure.PresentationQosPolicy::access_scope of the com.rti.dds.subscription.Subscriber is com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.GROUP_PRESENTATION_QOS or com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.HIGHEST_OFFERED_PRESENTATION_QOS and com.rti.dds.infrastructure.PresentationQosPolicy::ordered_access is com.rti.dds.infrastructure.true, the application is required to use this operation to access the samples in order across DataWriters of the same group (com.rti.dds.publication.Publisher with com.rti.dds.infrastructure.PresentationQosPolicy.access_scope set to com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.GROUP_PRESENTATION_QOS).

In the above case, the operation begin_access() must be called prior to calling any of the sample-accessing operations, com.rti.dds.subscription.Subscriber.get_datareaders on the com.rti.dds.subscription.Subscriber, and com.rti.ndds.example.FooDataReader.read, com.rti.ndds.example.FooDataReader.take, com.rti.ndds.example.FooDataReader.read_w_condition, and com.rti.ndds.example.FooDataReader.take_w_condition on any com.rti.dds.subscription.DataReader.

Once the application has finished accessing the data samples, it must call com.rti.dds.subscription.Subscriber.end_access.

The application is not required to call begin_access() / end_access() to access the samples in order if the PRESENTATION policy in the com.rti.dds.publication.Publisher has com.rti.dds.infrastructure.PresentationQosPolicy.access_scope set to something other than com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.GROUP_PRESENTATION_QOS. In this case, calling begin_access() / end_access() is not considered an error and has no effect.

Calls to begin_access() / end_access() may be nested and must be balanced.

Exceptions

One	of the Standard Return Codes or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

See Also: Access to data samples; com.rti.dds.subscription.Subscriber.get_datareaders; PRESENTATION

void end_access ( )

Indicates that the application has finished accessing the data samples in com.rti.dds.subscription.DataReader objects managed by the com.rti.dds.subscription.Subscriber.

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

This call must close a previous call to com.rti.dds.subscription.Subscriber.begin_access(), otherwise the operation will fail with the error com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET.

Exceptions

One	of the Standard Return Codes or com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET or com.rti.dds.infrastructure.RETCODE_NOT_ENABLED.

void copy_from_topic_qos	(	DataReaderQos	datareader_qos,
		TopicQos	topic_qos
	)

Copies the policies in the com.rti.dds.topic.TopicQos to the corresponding policies in the com.rti.dds.subscription.DataReaderQos.

Copies the policies in the com.rti.dds.topic.TopicQos to the corresponding policies in the com.rti.dds.subscription.DataReaderQos (replacing values in the com.rti.dds.subscription.DataReaderQos, if present).

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

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

Parameters

datareader_qos	<<inout>> com.rti.dds.subscription.DataReaderQos to be filled-up. Cannot be NULL.
topic_qos	<<in>> com.rti.dds.topic.TopicQos to be merged with com.rti.dds.subscription.DataReaderQos. Cannot be NULL.

Exceptions

One	of the Standard Return Codes

DomainParticipant get_participant ( )

Returns the com.rti.dds.domain.DomainParticipant to which the com.rti.dds.subscription.Subscriber belongs.

Returns: the com.rti.dds.domain.DomainParticipant to which the com.rti.dds.subscription.Subscriber belongs.

void delete_contained_entities ( )

Deletes all the entities that were created by means of the "create" operation on the com.rti.dds.subscription.Subscriber.

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

The operation will fail with com.rti.dds.infrastructure.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 com.rti.dds.subscription.DataReader cannot be deleted because the application has called a com.rti.ndds.example.FooDataReader.read or com.rti.ndds.example.FooDataReader.take operation and has not called the corresponding com.rti.ndds.example.FooDataReader.return_loan operation to return the loaned samples.

Once com.rti.dds.subscription.Subscriber.delete_contained_entities completes successfully, the application may delete the com.rti.dds.subscription.Subscriber, knowing that it has no contained com.rti.dds.subscription.DataReader objects.

Exceptions

One	of the Standard Return Codes, or com.rti.dds.infrastructure.RETCODE_PRECONDITION_NOT_MET

DataReader lookup_datareader_by_name_exp ( String datareader_name )

<<experimental>> <<eXtension>> Retrieves a com.rti.dds.subscription.DataReader contained within the com.rti.dds.subscription.Subscriber the com.rti.dds.subscription.DataReader entity name.

Every com.rti.dds.subscription.DataReader in the system has an entity name which is configured and stored in the <<eXtension>> EntityName policy, ENTITY_NAME.

This operation retrieves the com.rti.dds.subscription.DataReader within the com.rti.dds.subscription.Subscriber whose name matches the one specified. If there are several com.rti.dds.subscription.DataReader with the same name within the com.rti.dds.subscription.Subscriber, the operation returns the first matching occurrence.

Parameters

datareader_name <<in>> Entity name of the com.rti.dds.subscription.DataReader.

Returns: The first com.rti.dds.subscription.DataReader found with the specified name or NULL if it is not found.

See Also: com.rti.dds.domain.DomainParticipant.lookup_datareader_by_name_exp

Public Member Functions

Static Public Attributes

Detailed Description

Member Function Documentation