The DDS_Subscriber configures, creates, manages and destroys DDS_DataReaders. More...

Related Functions
(Note that these are not member functions.)
DDS_ReturnCode_t	DDS_Subscriber_enable (DDS_Subscriber s)
	Enables the DDS_Subscriber. More...

DDS_InstanceHandle_t	DDS_Subscriber_get_instance_handle (DDS_Subscriber s)
	This operation returns the InstanceHandle_t that identifies the Subscriber.

DDS_DomainParticipant	DDS_Subscriber_get_participant (DDS_Subscriber s)
	This operation returns the DDS_DomainParticipant this Subscriber belongs to.

DDS_StatusCondition	DDS_Subscriber_get_statuscondition (DDS_Subscriber s)
	This operation allows access to the DDS_StatusCondition associated with the Subscriber. More...

DDS_StatusMask	DDS_Subscriber_get_status_changes (DDS_Subscriber s)
	This returns the list of triggered communication statuses in the Subscriber. More...

DDS_DataReader	DDS_Subscriber_create_datareader (DDS_Subscriber s, DDS_TopicDescription a_topic, DDS_DataReaderQos qos, DDS_DataReaderListener a_listener, DDS_StatusMask mask)
	This operation creates a DDS_DataReader. More...

DDS_ReturnCode_t	DDS_Subscriber_delete_datareader (DDS_Subscriber s, DDS_DataReader a_datareader)
	This operation deletes a DataReader. More...

DDS_ReturnCode_t	DDS_Subscriber_delete_contained_entities (DDS_Subscriber s)
	This operation deletes all the DataReaders created by means of the DDS_Subscriber_create_datareader() operation on the Subscriber s. More...

DDS_DataReader	DDS_Subscriber_lookup_datareader (DDS_Subscriber s, const char *topic_name)
	This operation retrieves a previously-created DDS_DataReader contained in the Subscriber, attached to a Topic named topic_name. More...

DDS_ReturnCode_t	DDS_Subscriber_get_datareaders (DDS_Subscriber s, DDS_DataReaderSeq *readers, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)
	This operation allows the application to access DataReader objects that contain samples with the specified sample_states, view_states, and instance_states. More...

DDS_ReturnCode_t	DDS_Subscriber_notify_datareaders (DDS_Subscriber s)
	This operation invokes the DDS_DataReaderListener on_data_available operation on any contained DataReader entities with a DATA_AVAILABLE status that is considered changed.

DDS_ReturnCode_t	DDS_Subscriber_set_qos (DDS_Subscriber s, DDS_SubscriberQos *qos)
	Sets the DDS_SubscriberQos values. More...

DDS_ReturnCode_t	DDS_Subscriber_get_qos (DDS_Subscriber s, DDS_SubscriberQos *qos)
	Returns the current DDS_SubscriberQos settings held in the Subscriber s. More...

DDS_ReturnCode_t	DDS_Subscriber_set_listener (DDS_Subscriber s, DDS_SubscriberListener *a_listener, DDS_StatusMask mask)
	Installs a DDS_SubscriberListener on Subscriber s. More...

DDS_ReturnCode_t	DDS_Subscriber_set_listener_cd (DDS_Subscriber s, DDS_SubscriberListener_cd listener_cd, DDS_StatusMask mask, void callback_data)
	Installs a DDS_SubscriberListener_cd on Subscriber s. More...

DDS_SubscriberListener *	DDS_Subscriber_get_listener (DDS_Subscriber s)
	This operation returns the currently installed DDS_SubscriberListener. More...

DDS_SubscriberListener_cd *	DDS_Subscriber_get_listener_cd (DDS_Subscriber s)
	This operation returns the currently installed DDS_SubscriberListener_cd. More...

DDS_ReturnCode_t	DDS_Subscriber_begin_access (DDS_Subscriber s)
	This operation indicates that the application is about to access the data samples in any of the DataReader objects contained in the Subscriber s. More...

DDS_ReturnCode_t	DDS_Subscriber_end_access (DDS_Subscriber s)
	This operation closes a corresponding DDS_Subscriber_begin_access().

DDS_ReturnCode_t	DDS_Subscriber_set_default_datareader_qos (DDS_Subscriber s, const DDS_DataReaderQos *qos)
	Sets the default DDS_DataReaderQos held in the Subscriber. More...

DDS_ReturnCode_t	DDS_Subscriber_get_default_datareader_qos (DDS_Subscriber s, DDS_DataReaderQos *qos)
	Provides access to the default DDS_DataReaderQos settings held in the Subscriber s. More...

DDS_ReturnCode_t	DDS_Subscriber_copy_from_topic_qos (DDS_Subscriber s, DDS_DataReaderQos a_datareader_qos, DDS_TopicQos a_topic_qos)
	This operation copies the QoS settings in a_topic_qos to the corresponding settings in a_datareader_qos. More...

Detailed Description

The DDS_Subscriber configures, creates, manages and destroys DDS_DataReaders.

Friends And Related Function Documentation

◆ DDS_Subscriber_begin_access()

DDS_ReturnCode_t DDS_Subscriber_begin_access ( DDS_Subscriber s )

The application is expected to use this operation only if PRESENTATION QosPolicy of the Subscriber has the access_scope set to GROUP. [Otherwise this routine has no effect.]

◆ DDS_Subscriber_copy_from_topic_qos()

DDS_ReturnCode_t DDS_Subscriber_copy_from_topic_qos	(	DDS_Subscriber	s,
		DDS_DataReaderQos *	a_datareader_qos,
		DDS_TopicQos *	a_topic_qos
	)

The a_datareader_qos parameter is populated with a copy of the QoS policies from the a_topic_qos structure. QoS entries in the datareader qos structure will be overwritten with the values from the topic.

◆ DDS_Subscriber_create_datareader()

DDS_DataReader DDS_Subscriber_create_datareader	(	DDS_Subscriber	s,
		DDS_TopicDescription	a_topic,
		DDS_DataReaderQos *	qos,
		DDS_DataReaderListener *	a_listener,
		DDS_StatusMask	mask
	)

The created DataReader is contained within the Subscriber s. It is associated with the Topic, ContentFilteredTopic, or MultiTopic indicated by a_topic, and has the DDS_DataReaderQos indicated by qos. The qos argument may be passed DDS_DATAREADER_QOS_DEFAULT, which indicates that the Subscriber should use its currently configured default data reader QoS values. The DDS_DataReaderListener a_listener, is installed at creation time.

The created DataReader (if not NULL) must be destroyed by a call to DDS_Subscriber_delete_datareader().

This routine will fail if the provided QoS settings are internally inconsistent. In this case, the routine will return NULL.

◆ DDS_Subscriber_delete_contained_entities()

DDS_ReturnCode_t DDS_Subscriber_delete_contained_entities ( DDS_Subscriber s )

This routine will recursively call the corresponding delete_contained_entities() operation on each of the contained DataReader objects. If successful, this operation will recursively delete all objects contained with this Subscriber. After successful execution, the application may delete the Subscriber by calling DDS_DomainParticipant_delete_subscriber().

If any of the objects cannot be deleted, this routine will return DDS_RETCODE_PRECONDITION_NOT_MET.

◆ DDS_Subscriber_delete_datareader()

DDS_ReturnCode_t DDS_Subscriber_delete_datareader	(	DDS_Subscriber	s,
		DDS_DataReader	a_datareader
	)

If the provided DataReader a_datareader was not created by Subscriber s, the routine will fail and will return DDS_RETCODE_PRECONDITION_NOT_MET. If the indicated DataReader has any outstanding DDS_ReadCondition or DDS_QueryCondition objects the routine will fail and will return DDS_RETCODE_PRECONDITION_NOT_MET. If the indicated DataReader has any outstanding 'loans' (from read() or take() operations), the routine will fail and will return DDS_RETCODE_PRECONDITION_NOT_MET.

◆ DDS_Subscriber_enable()

DDS_ReturnCode_t DDS_Subscriber_enable ( DDS_Subscriber s )

A Subscriber is created either enabled or not based on the DDS_DomainParticipantQos setting entity_factory. When a Subscriber is not enabled, only the following sub-set of all Subscriber operations are legal:

operations to get and set QoS policies,
factory operations (create, delete),
get_statuscondition(),
get_status_changes(),
lookup operations

Any other Subscriber operation may return the DDS_NOT_ENABLED error. DDS_Subscriber_enable() may be called on an already enabled Subscriber [it will have no effect].

◆ DDS_Subscriber_get_datareaders()

DDS_ReturnCode_t DDS_Subscriber_get_datareaders	(	DDS_Subscriber	s,
		DDS_DataReaderSeq *	readers,
		DDS_SampleStateMask	sample_states,
		DDS_ViewStateMask	view_states,
		DDS_InstanceStateMask	instance_states
	)

If the PRESENTATION QosPolicy of the Subscriber to which the DataReader belongs has the access_scope set to GROUP, this operation should be invoked only inside a begin_access/end_access block. Otherwise it will return the error PRECONDITION_NOT_MET.

The returned collection of DataReader objects may either be a set (containing each DataReader at most once in no specified order), or a list (containing each DataReader one or more times in a specific order).

If PRESENTATION access_scope is INSTANCE or TOPIC, the returned collection is a set.
If PRESENTATION access_scope is GROUP and ordered_access is set to TRUE, then the returned collection is a list.

This difference supports alternate access mechanisms.

◆ DDS_Subscriber_get_default_datareader_qos()

DDS_ReturnCode_t DDS_Subscriber_get_default_datareader_qos	(	DDS_Subscriber	s,
		DDS_DataReaderQos *	qos
	)

The provided qos argument is populated with the current default qos settings.

◆ DDS_Subscriber_get_listener()

DDS_SubscriberListener * DDS_Subscriber_get_listener ( DDS_Subscriber s )

Note: Because the infrastructure makes a copy of the listener provided in DDS_Subscriber_set_listener(), the returned structure pointer will not match the pointer originally provided. However, the function pointers within the structure will match. Also, the application should not free the data referenced by the returned pointer.

◆ DDS_Subscriber_get_listener_cd()

DDS_SubscriberListener_cd * DDS_Subscriber_get_listener_cd ( DDS_Subscriber s )

Note: Because the infrastructure does not make a copy of the listener provided in DDS_Subscriber_set_listener_cd(), the returned structure pointer will match the pointer originally provided. The application should not free the data referenced by the returned pointer.

◆ DDS_Subscriber_get_qos()

DDS_ReturnCode_t DDS_Subscriber_get_qos	(	DDS_Subscriber	s,
		DDS_SubscriberQos *	qos
	)

The qos parameter is populated with a copy of the current Subscriber QoS properties.

Note: The qos structure may contain sequences or strings that are populated with dynamic memory. The caller is responsible for freeing the dynamic memory of these items.
For example, the sequence 'qos->group_data' may have dynamically allocated memory assigned. This can be released by a call to seq_clear(&qos->group_data).

◆ DDS_Subscriber_get_status_changes()

DDS_StatusMask DDS_Subscriber_get_status_changes ( DDS_Subscriber s )

If the Subscriber is not enabled, all statuses will be untriggered. The list returned by get_status_changes may be empty. The list of statuses returned by get_status_changes operation contains statuses that are triggered on the Subscriber itself and does not include statuses from contained DataReader objects.

◆ DDS_Subscriber_get_statuscondition()

DDS_StatusCondition DDS_Subscriber_get_statuscondition ( DDS_Subscriber s )

The returned condition can be added to a DDS_WaitSet.

◆ DDS_Subscriber_lookup_datareader()

DDS_DataReader DDS_Subscriber_lookup_datareader	(	DDS_Subscriber	s,
		const char *	topic_name
	)

If multiple DataReaders are found, one of them will be returned. If no matching DataReader is found, this routine will return NULL.

This routine is useful to obtain access to a particular built-in DataReader.

◆ DDS_Subscriber_set_default_datareader_qos()

DDS_ReturnCode_t DDS_Subscriber_set_default_datareader_qos	(	DDS_Subscriber	s,
		const DDS_DataReaderQos *	qos
	)

This default qos will be used during subsequent calls to DDS_Subscriber_create_datareader() if the special DDS_DATAREADER_QOS_DEFAULT value is provided for qos.
This routine may fail if the provided qos argument is not internally consistent. In this case, DDS_INCONSISTENT_POLICY will be returned, and no changes will be made to the Subscriber.

◆ DDS_Subscriber_set_listener()

DDS_ReturnCode_t DDS_Subscriber_set_listener	(	DDS_Subscriber	s,
		DDS_SubscriberListener *	a_listener,
		DDS_StatusMask	mask
	)

Only one listener may be attached to a Subscriber at a time. A call to set_listener() will replace any current listener with a_listener.

a_listener can be NULL, which indicates a listener that does nothing.

The infrastructure will make an internal copy of the listener structure so that it need not be persisted by the application.

◆ DDS_Subscriber_set_listener_cd()

DDS_ReturnCode_t DDS_Subscriber_set_listener_cd	(	DDS_Subscriber	s,
		DDS_SubscriberListener_cd *	listener_cd,
		DDS_StatusMask	mask,
		void *	callback_data
	)

Only one listener may be attached to a Subscriber at a time. A call to set_listener_cd() will replace any current listener with a_listener.