.. _dds_layers_subscription_accessing_data:

Accessing received data
=======================

.. include:: ../../../safety_manual/rules/RULE_OPERATION_PHASE_ACTIONS.inc
.. include:: ../../../safety_manual/rules/RULE_LISTENER_OPERATION.inc

The application can access and consume the data values received on the :ref:`dds_layers_subscription_datareader` by taking a sample.
Using the ``DataReader::take_next_sample`` reads the next, non-previously accessed data value available on the DataReader, and stores it in the provided data object.

When taking data, the returned samples are also removed from the DataReader, so they are no longer accessible.

When there is no data in the DataReader matching the required conditions, all the operations will return ``NO_DATA`` and output parameter will remain unchanged.

In addition to the data values, the data access operations also provide SampleInfo instances with additional
information that help interpreting the returned data values, like the originating :ref:`dds_layers_publication_datawriter` or the publication time stamp.
Refer to the :ref:`dds_layers_subscription_sampleinfo` section for an extensive description of its contents.

.. _dds_layer_publisher_typedDataReader:

Using the TypedDataReader
-------------------------

.. note::

   In order to provide a type safe API, Safe DDS provides a ``TypedDataReader`` class.

``TypedDataReader`` class is a specialization of the ``DataReader`` class, and it is obtained by calling the ``TypedDataReader::downcast`` method and its constructed using a :ref:`typesupport` class that must be previously :ref:`registered in the DomainParticipant <typesupport_register_type>` with a :ref:`dds_layers_topic` name that matches the one used to create the ``DataReader``.

Once the ``TypedDataReader`` reference is obtained, the ``take_next_sample`` method can be used to retrieve data.

The ``take_next_sample`` function takes two arguments:

* A reference to a typed object to be used as output argument.
* A ``SampleInfo`` reference to be used as output argument.

.. note::

   If :ref:`Safe DDS Static API <dds_layers_create_datareader_static>` is used, there is no need to use the ``TypedDataReader::downcast`` method, since the ``StaticDataReader`` is already a ``TypedDataReader``.

Example
"""""""

.. literalinclude:: ../../../code/entity_creation/main.cpp
   :language: c++
   :start-after: // DDS_READ_DATA
   :end-before: //! DDS_READ_DATA
   :dedent: 8

.. _dds_layer_subscriber_accessreceived_listener:

Accessing data on callbacks
---------------------------

When the DataReader receives new data values from any matching DataWriter, it informs the application through two Listener callbacks:

* ``DataReaderListener::on_data_available``.
* ``SubscriberListener::on_data_on_readers``.

These callbacks can be used to retrieve the newly arrived data

.. note::
   If several new data changes are received at once, the callbacks may be triggered just once, instead of once per change.
   The application must keep *taking* until no new changes are available.

Example
"""""""

.. literalinclude:: ../../../code/entity_creation/main.cpp
   :language: c++
   :start-after: // DDS_LISTENER_READ_DATA
   :end-before: //! DDS_LISTENER_READ_DATA