Go2Py_SIM/cpp_bridge/thirdparty/include/ddscxx/dds/sub/TDataReader.hpp

#ifndef OMG_DDS_SUB_TDATA_READER_HPP_
#define OMG_DDS_SUB_TDATA_READER_HPP_

/* Copyright 2010, Object Management Group, Inc.
 * Copyright 2010, PrismTech, Corp.
 * Copyright 2010, Real-Time Innovations, Inc.
 * All rights reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
#include <dds/core/detail/conformance.hpp>
#include <dds/sub/AnyDataReader.hpp>
#include <dds/topic/ContentFilteredTopic.hpp>
#include <dds/topic/TopicInstance.hpp>
#include <dds/sub/LoanedSamples.hpp>
#include <dds/sub/Subscriber.hpp>


namespace dds
{
namespace sub
{
template <typename T, template <typename Q> class DELEGATE>
class DataReader;

template <typename T>
class DataReaderListener;
}
}

/**
 * @brief
 * DataReader allows the applicatin to access published sample data.
 *
 * A DataReader allows the application:
 * - to declare the data it wishes to receive (i.e., make a subscription)
 * - to access the data received by the attached Subscriber
 *
 * A DataReader refers to exactly one TopicDescription (either a Topic, a
 * ContentFilteredTopic or a MultiTopic) that identifies the samples to be
 * read. The Topic must exist prior to the DataReader creation.
 *
 * A DataReader is attached to exactly one Subscriber which acts as a factory
 * for it.
 *
 * The DataReader may give access to several instances of the data type, which
 * are distinguished from each other by their key.
 *
 * The pre-processor generates from IDL type descriptions the application
 * DataReader<type> classes. For each application data type that is used as Topic
 * data type, a typed class DataReader<type> is derived from the AnyDataReader
 * class.
 *
 * For instance, for an application, the definitions are located in the Foo.idl file.
 * The pre-processor will generate a ccpp_Foo.h include file.
 *
 * <b>General note:</b> The name ccpp_Foo.h is derived from the IDL file Foo.idl,
 * that defines Foo::Bar, for all relevant DataReader<Foo::Bar> operations.
 *
 * @note Apart from idl files, Google protocol buffers are also supported. For the
 *       API itself, it doesn't matter if the type header files were generated from
 *       idl or protocol buffers. The resulting API usage and includes remain the same.
 *
 * @anchor anchor_dds_sub_datareader_example
 * <b>Example</b>
 * @code{.cpp}
 * // Default creation of a DataReader
 * dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
 * dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");
 * dds::sub::Subscriber subscriber(participant);
 * dds::sub::DataReader<Foo::Bar> reader(subscriber, topic);
 *
 * {
 *     // Default read of a sample on the DataReader
 *     dds::sub::LoanedSamples<Foo::Bar> samples;
 *     samples = reader.read();
 *
 *     // Default way of accessing the loaned samples
 *     dds::sub::LoanedSamples<Foo::Bar>::const_iterator it;
 *     for (it = samples.begin(); it != samples.end(); ++it) {
 *         const dds::sub::Sample<Foo::Bar>& sample = *it;
 *         const Foo::Bar& data = sample.data();
 *         const dds::sub::SampleInfo& info = sample.info();
 *         // Use sample data and meta information.
 *     }
 * }
 * // Like the name says, the read samples are loans from the DataReader. The loan
 * // was automatically returned when the LoanedSamples went out of scope.
 * @endcode
 *
 * @see for more information: @ref DCPS_Modules_Subscription "Subscription concept"
 * @see for more information: @ref DCPS_Modules_Subscription_DataReader "DataReader concept"
 */
template <typename T, template <typename Q> class DELEGATE>
class dds::sub::DataReader : public dds::sub::TAnyDataReader< DELEGATE<T> >
{

public:
    /**
     * Local convenience typedef for dds::sub::DataReaderListener.
     */
    typedef ::dds::sub::DataReaderListener<T> Listener;

public:

    /**
     * The Selector class is used by the DataReader to compose read operations.
     *
     * A Selector can perform complex data selections, such as per-instance selection,
     * content and status filtering, etc, when reading or taking samples. These settings
     * on a Selector can be concatenated.
     *
     * The DataReader has the select() operation, which can be used to aqcuire the Selector
     * functionality on the reader implicitly.
     * @code{.cpp}
     * // Take a maximum of 3 new samples of a certain instance.
     * samples = reader.select()
     *                     .max_samples(3)
     *                     .state(dds::sub::status::DataState::new_data())
     *                     .instance(someValidInstanceHandle)
     *                     .take();
     * @endcode
     * However, this will create and destroy a Selector for every read, which is not
     * very performance friendly.
     *
     * The performance can be increase by creating a Selector up front and doing the
     * reading on that Selector directly and re-using it.
     * @code{.cpp}
     * // Create a Selector as selective reader up front.
     * dds::sub::DataReader<Foo::Bar>::Selector selectiveReader(reader);
     * // Configure it to take a maximum of 3 new samples of a certain instance
     * selectiveReader.max_samples(3);
     * selectiveReader.state(dds::sub::status::DataState::new_data());
     * selectiveReader.instance(someValidInstanceHandle);
     *
     * // Use the configured Selector to -take- a maximum of 3 new samples of a
     * // certain instance (which it was configured to do).
     * // This can be used in loops for example, reducing the need for creating
     * // implicit Selectors for every take.
     * samples = selectiveReader.take();
     * @endcode
     *
     * <i>Defaults</i>
     * Element         | Default Value
     * --------------- | --------------------
     * state           | dds::sub::status::DataState::any
     * content         | Empty dds::sub::Query
     * max_samples     | dds::core::LENGTH_UNLIMITED
     * instance        | dds::core::InstanceHandle nil
     *
     * @see for more information: @link dds::sub::DataReader::select() DataReader select() @endlink
     */
    class Selector
    {
    public:
        /**
         * Construct a Selector for a DataReader.
         *
         * @param dr DataReader
         */
        Selector(DataReader& dr);

        /**
         * Set InstanceHandle to filter with during the read or take.
         *
         * <i>Example</i><br>
         * Read only samples of the given instance.
         * @code{.cpp}
         * dds::core::InstanceHandle hdl = someValidInstanceHandle;
         *
         * // Implicit use of Selector
         * samples = reader.select().instance(hdl).read();
         *
         * // Explicit use of Selector
         * dds::sub::DataReader<Foo::Bar>::Selector selectiveReader(reader);
         * selectiveReader.instance(hdl);
         * samples = selectiveReader.read();
         * @endcode
         * See also @link dds::sub::DataReader::select() DataReader select() @endlink operation.
         *
         * @param handle the InstanceHandle to read/take for
         * @return a Selector to be able to concatenate Selector settings.
         */
        Selector& instance(const dds::core::InstanceHandle& handle);

        /**
         * Set next InstanceHandle to filter with during the read or take.
         *
         * <i>Example</i><br>
         * Read all samples, instance by instance.
         * @code{.cpp}
         * // Implicit use of Selector
         * {
         *     // Get sample(s) of first instance
         *     dds::core::InstanceHandle hdl; //nil
         *     samples = reader.select().next_instance(hdl).read();
         *     while (samples.length() > 0) {
         *         // Handle the sample(s) of this instance (just the first one in this case)
         *         const dds::sub::Sample<Foo::Bar>& sample = *(samples.begin());
         *         // Get sample(s) of the next instance
         *         hdl = sample.info().instance_handle();
         *         samples = reader.select().next_instance(hdl).read();
         *     }
         * }
         *
         * // Explicit use of Selector
         * {
         *     // Get sample(s) of first instance
         *     dds::sub::DataReader<Foo::Bar>::Selector selectiveReader(reader);
         *     dds::core::InstanceHandle hdl; //nil
         *     selectiveReader.next_instance(hdl);
         *     samples = selectiveReader.read();
         *     while (samples.length() > 0) {
         *         // Handle the sample(s) of this instance (just the first one in this case)
         *         const dds::sub::Sample<Foo::Bar>& sample = *(samples.begin());
         *         // Get sample(s) of the next instance
         *         hdl = sample.info().instance_handle();
         *         selectiveReader.next_instance(hdl);
         *         samples = selectiveReader.read();
         *     }
         * }
         * @endcode
         * See also @link dds::sub::DataReader::select() DataReader select() @endlink operation.
         *
         * @param handle the 'previous' InstanceHandle associated with new the read/take
         * @return a Selector to be able to concatenate Selector settings.
         */
        Selector& next_instance(const dds::core::InstanceHandle& handle);

        /**
         * Set DataState to filter with during the read or take.
         *
         * <i>Example</i><br>
         * Read only new data.
         * @code{.cpp}
         * // DataState to filter only new data
         * dds::sub::status::DataState newData = dds::sub::status::DataState::new_data();
         *
         * // Implicit use of Selector
         * samples = reader.select().state(newData).read();
         *
         * // Explicit use of Selector
         * dds::sub::DataReader<Foo::Bar>::Selector selectiveReader(reader);
         * selectiveReader.state(newData);
         * samples = selectiveReader.read();
         * @endcode
         * See also @link dds::sub::DataReader::select() DataReader select() @endlink operation.
         *
         * @param state the requested DataState of the samples
         * @return a Selector to be able to concatenate Selector settings.
         */
        Selector& state(const dds::sub::status::DataState& state);

        /**
         * Set the Query to filter with during the read or take.
         *
         * <i>Example</i><br>
         * Read only samples that will be filtered according to the given dds::sub::Query.
         * @code{.cpp}
         * // Assume data type has an element called long_1
         * dds::sub::Query query(reader, "long_1 > 1 and long_1 < 7");
         *
         * // Implicit use of Selector
         * samples = reader.select().content(query).read();
         *
         * // Explicit use of Selector
         * dds::sub::DataReader<Foo::Bar>::Selector selectiveReader(reader);
         * selectiveReader.content(query);
         * samples = selectiveReader.read();
         * @endcode
         * See also @link dds::sub::DataReader::select() DataReader select() @endlink operation.
         *
         * @param query the Query to apply to the selector
         * @return a Selector to be able to concatenate Selector settings.
         */
        Selector& content(const dds::sub::Query& query);

        /**
         * Set max_samples to limit the number of sample to get during the read or take.
         *
         * <i>Example</i><br>
         * Read a maximum of three samples.
         * @code{.cpp}
         * // Implicit use of Selector
         * samples = reader.select().max_samples(3).read();
         *
         * // Explicit use of Selector
         * dds::sub::DataReader<Foo::Bar>::Selector selectiveReader(reader);
         * selectiveReader.max_samples(3);
         * samples = selectiveReader.read();
         * @endcode
         * See also @link dds::sub::DataReader::select() DataReader select() @endlink operation.
         *
         * @param maxsamples maximum number of samples to read/take
         * @return a Selector to be able to concatenate Selector settings.
         */
        Selector& max_samples(uint32_t maxsamples);

        /**
         * This operation works the same as the @link DataReader::read() default
         * DataReader read() @endlink, except that it is performed on this Selector
         * with possible filters set.
         *
         * @return          The samples in the LoanedSamples container
         * @throws dds::core::Error
         *                  An internal error has occurred.
         * @throws dds::core::NullReferenceError
         *                  The entity was not properly created and references to dds::core::null.
         * @throws dds::core::AlreadyClosedError
         *                  The entity has already been closed.
         * @throws dds::core::OutOfResourcesError
         *                  The Data Distribution Service ran out of resources to
         *                  complete this operation.
         * @throws dds::core::NotEnabledError
         *                  The DataReader has not yet been enabled.
         */
        dds::sub::LoanedSamples<T> read();

        /**
         * This operation works the same as the @link DataReader::take() default
         * DataReader take() @endlink, except that it is performed on this Selector
         * with possible filters set.
         *
         * @return          The samples in the LoanedSamples container
         * @throws dds::core::Error
         *                  An internal error has occurred.
         * @throws dds::core::NullReferenceError
         *                  The entity was not properly created and references to dds::core::null.
         * @throws dds::core::AlreadyClosedError
         *                  The entity has already been closed.
         * @throws dds::core::OutOfResourcesError
         *                  The Data Distribution Service ran out of resources to
         *                  complete this operation.
         * @throws dds::core::NotEnabledError
         *                  The DataReader has not yet been enabled.
         */
        dds::sub::LoanedSamples<T> take();

        // --- Forward Iterators: --- //
        /**
         * This operation works the same as the @link DataReader::read(SamplesFWIterator sfit, uint32_t max_samples)
         * forward iterator DataReader read() @endlink, except that it is performed on this
         * Selector with possible filters set.
         *
         * @param  sfit     Forward-inserting container iterator
         * @param  max_samples Maximum samples to read and copy into the given container
         * @return          The number of samples in the LoanedSamples container
         * @throws dds::core::Error
         *                  An internal error has occurred.
         * @throws dds::core::NullReferenceError
         *                  The entity was not properly created and references to dds::core::null.
         * @throws dds::core::AlreadyClosedError
         *                  The entity has already been closed.
         * @throws dds::core::OutOfResourcesError
         *                  The Data Distribution Service ran out of resources to
         *                  complete this operation.
         * @throws dds::core::NotEnabledError
         *                  The DataReader has not yet been enabled.
         */
        template <typename SamplesFWIterator>
        uint32_t
        read(SamplesFWIterator sfit, uint32_t max_samples);

        /**
         * This operation works the same as the @link DataReader::take(SamplesFWIterator sfit, uint32_t max_samples)
         * forward iterator DataReader take() @endlink, except that it is performed on this
         * Selector with possible filters set.
         *
         * @param  sfit     Forward-inserting container iterator
         * @param  max_samples Maximum samples to read and copy into the given container
         * @return          The number of samples in the given container
         * @throws dds::core::Error
         *                  An internal error has occurred.
         * @throws dds::core::NullReferenceError
         *                  The entity was not properly created and references to dds::core::null.
         * @throws dds::core::AlreadyClosedError
         *                  The entity has already been closed.
         * @throws dds::core::OutOfResourcesError
         *                  The Data Distribution Service ran out of resources to
         *                  complete this operation.
         * @throws dds::core::NotEnabledError
         *                  The DataReader has not yet been enabled.
         */
        template <typename SamplesFWIterator>
        uint32_t
        take(SamplesFWIterator sfit,  uint32_t max_samples);

        // --- Back-Inserting Iterators: --- //
        /**
         * This operation works the same as the @link DataReader::read(SamplesBIIterator sbit)
         * backward iterator DataReader read() @endlink, except that it is performed on this
         * Selector with possible filters set.
         *
         * @param  sbit     Back-inserting container iterator
         * @return          The number of samples in the given container
         * @throws dds::core::Error
         *                  An internal error has occurred.
         * @throws dds::core::NullReferenceError
         *                  The entity was not properly created and references to dds::core::null.
         * @throws dds::core::AlreadyClosedError
         *                  The entity has already been closed.
         * @throws dds::core::OutOfResourcesError
         *                  The Data Distribution Service ran out of resources to
         *                  complete this operation.
         * @throws dds::core::NotEnabledError
         *                  The DataReader has not yet been enabled.
         */
        template <typename SamplesBIIterator>
        uint32_t
        read(SamplesBIIterator sbit);

        /**
         * This operation works the same as the @link DataReader::take(SamplesBIIterator sbit)
         * backward iterator DataReader take() @endlink, except that it is performed on this
         * Selector with possible filters set.
         *
         * @param  sbit     Back-inserting container iterator
         * @return          The number of samples in the given container
         * @throws dds::core::Error
         *                  An internal error has occurred.
         * @throws dds::core::NullReferenceError
         *                  The entity was not properly created and references to dds::core::null.
         * @throws dds::core::AlreadyClosedError
         *                  The entity has already been closed.
         * @throws dds::core::OutOfResourcesError
         *                  The Data Distribution Service ran out of resources to
         *                  complete this operation.
         * @throws dds::core::NotEnabledError
         *                  The DataReader has not yet been enabled.
         */
        template <typename SamplesBIIterator>
        uint32_t
        take(SamplesBIIterator sbit);

    private:
        typename DELEGATE<T>::Selector impl_;
    };

    /**
     * The ManipulatorSelector class is used by the DataReader to compose streaming
     * read operations.
     *
     * A ManipulatorSelector can perform complex data selections, such as per-instance
     * selection, content and status filtering, etc, when reading or taking samples
     * through the streaming operator.
     *
     * <i>Convenience functors</i><br>
     * The following convenience functors use a ManipulatorSelector implicitly and can be
     * used in the streaming operator:
     * - dds::sub::read
     * - dds::sub::take
     * - dds::sub::max_samples
     * - dds::sub::content
     * - dds::sub::state
     * - dds::sub::instance
     * - dds::sub::next_instance
     *
     * @code{.cpp}
     * // Take a maximum of 3 new samples of a certain instance.
     * reader >> dds::sub::take
     *        >> dds::sub::max_samples(3)
     *        >> dds::sub::state(dds::sub::status::DataState::new_data())
     *        >> dds::sub::instance(someValidInstanceHandle)
     *        >> samples;
     * @endcode
     * However, this will create and destroy ManipulatorSelectors and Functors for
     * every read, which is not very performance friendly.
     *
     * The performance can be increase by creating a ManipulatorSelector up front and
     * doing the reading on that ManipulatorSelector directly and re-using it.
     * @code{.cpp}
     * // Create a ManipulatorSelector as selective reader up front.
     * dds::sub::DataReader<Foo::Bar>::ManipulatorSelector selectiveReader(reader);
     * // Configure it to take a maximum of 3 new samples of a certain instance
     * selectiveReader.max_samples(3);
     * selectiveReader.state(dds::sub::status::DataState::new_data());
     * selectiveReader.instance(someValidInstanceHandle);
     * selectiveReader.read_mode(false); // take
     *
     * // Use the configured ManipulatorSelector to -take- a maximum of 3 samples of a
     * // certain instance (which it was configured to do).
     * // This can be used in loops for example, reducing the need for creating
     * // implicit ManipulatorSelectors for every take.
     * selectiveReader >> samples;
     * @endcode
     *
     * <i>Defaults</i>
     * Element         | Default Value
     * --------------- | --------------------
     * read_mode       | true (read)
     * state           | dds::sub::status::DataState::any
     * content         | Empty dds::sub::Query
     * max_samples     | dds::core::LENGTH_UNLIMITED
     * instance        | dds::core::InstanceHandle nil
     *
     * @see for more information: @link dds::sub::DataReader::operator>>(dds::sub::LoanedSamples<T>& ls) DataReader stream operator>> @endlink
     */
    class ManipulatorSelector
    {
    public:
        /**
         * Construct a ManipulatorSelector for a DataReader.
         *
         * See also @link dds::sub::DataReader::operator>>(dds::sub::LoanedSamples<T>& ls)
         * DataReader stream operator>> @endlink
         *
         * @param DataReader
         */
        ManipulatorSelector(DataReader& dr);

        /**
         * Get the read_mode.
         *
         * The read_mode specifies if a sample should be read or taken:
         * - true = read (default)
         * - false = take
         *
         * @return true if read_mode is set to read
         */
        bool read_mode();

        /**
         * Set the read_mode.
         *
         * The read_mode specifies if a sample should be read or taken:
         * - true = read (default)
         * - false = take
         *
         * <i>Convenience Functor:</i> dds::sub::read<br>
         * <i>Convenience Functor:</i> dds::sub::take
         *
         * <i>Example</i><br>
         * Determine to read or take samples.
         * @code{.cpp}
         * // No usage of ManipulatorSelector, means a read iso take as default.
         * reader >> samples;
         *
         * // Implicit use of ManipulatorSelector
         * reader >> dds::sub::read >> samples;
         * reader >> dds::sub::take >> samples;
         *
         * // Explicit use of ManipulatorSelector
         * dds::sub::DataReader<Foo::Bar>::ManipulatorSelector readingReader(reader);
         * readingReader.read_mode(true); // Read, which is already the default.
         * readingReader >> samples;
         *
         * dds::sub::DataReader<Foo::Bar>::ManipulatorSelector takingReader(reader);
         * takingReader.read_mode(false); // Take.
         * takingReader >> samples;
         * @endcode
         * See also @link dds::sub::DataReader::operator>>(dds::sub::LoanedSamples<T>& ls)
         * DataReader stream operator>> @endlink
         *
         * @param readmode the read mode of the DataReader
         */
        void read_mode(bool readmode);

        /**
         * Set max_samples to limit the number of sample to get during the read or take.
         *
         * <i>Convenience Functor:</i> dds::sub::max_samples
         *
         * <i>Example</i><br>
         * Read a maximum of three samples.
         * @code{.cpp}
         * // Implicit use of ManipulatorSelector
         * reader >> dds::sub::max_samples(3) >> samples;
         *
         * // Explicit use of ManipulatorSelector
         * dds::sub::DataReader<Foo::Bar>::ManipulatorSelector selectiveReader(reader);
         * selectiveReader.max_samples(3);
         * selectiveReader >> samples;
         * @endcode
         * See also @link dds::sub::DataReader::operator>>(dds::sub::LoanedSamples<T>& ls)
         * DataReader stream operator>> @endlink
         *
         * @param n maximum number of samples
         */
        ManipulatorSelector& max_samples(uint32_t n);

        /**
         * Set InstanceHandle to filter with during the read or take.
         *
         * <i>Convenience Functor:</i> dds::sub::instance
         *
         * <i>Example</i><br>
         * Read only samples of the given instance.
         * @code{.cpp}
         * dds::core::InstanceHandle hdl = someValidInstanceHandle;
         *
         * // Implicit use of ManipulatorSelector
         * reader >> dds::sub::instance(hdl) >> samples;
         *
         * // Explicit use of ManipulatorSelector
         * dds::sub::DataReader<Foo::Bar>::ManipulatorSelector selectiveReader(reader);
         * selectiveReader.instance(hdl);
         * selectiveReader >> samples;
         * @endcode
         * See also @link dds::sub::DataReader::operator>>(dds::sub::LoanedSamples<T>& ls)
         * DataReader stream operator>> @endlink
         *
         * @param handle the InstanceHandle for the read/take
         */
        ManipulatorSelector& instance(const dds::core::InstanceHandle& handle);

        /**
         * Set next InstanceHandle to filter with during the read or take.
         *
         * <i>Convenience Functor:</i> dds::sub::next_instance
         *
         * <i>Example</i><br>
         * Read all samples, instance by instance.
         * @code{.cpp}
         * // Implicit use of ManipulatorSelector
         * {
         *     // Get sample(s) of first instance
         *     dds::core::InstanceHandle hdl; //nil
         *     reader >> dds::sub::next_instance(hdl) >> samples;
         *     while (samples.length() > 0) {
         *         // Handle the sample(s) of this instance (just the first one in this case)
         *         const dds::sub::Sample<Foo::Bar>& sample = *(samples.begin());
         *         // Get sample(s) of the next instance
         *         hdl = sample.info().instance_handle();
         *         reader >> dds::sub::next_instance(hdl) >> samples;
         *     }
         * }
         *
         * // Explicit use of ManipulatorSelector
         * {
         *     // Get sample(s) of first instance
         *     dds::sub::DataReader<Foo::Bar>::ManipulatorSelector selectiveReader(reader);
         *     dds::core::InstanceHandle hdl; //nil
         *     selectiveReader.next_instance(hdl);
         *     selectiveReader >> samples;
         *     while (samples.length() > 0) {
         *         // Handle the sample(s) of this instance (just the first one in this case)
         *         const dds::sub::Sample<Foo::Bar>& sample = *(samples.begin());
         *         // Get sample(s) of the next instance
         *         hdl = sample.info().instance_handle();
         *         selectiveReader.next_instance(hdl);
         *         selectiveReader >> samples;
         *     }
         * }
         * @endcode
         * See also @link dds::sub::DataReader::operator>>(dds::sub::LoanedSamples<T>& ls)
         * DataReader stream operator>> @endlink
         *
         * @param handle the 'previous' InstanceHandle associated with new the read/take
         */
        ManipulatorSelector& next_instance(const dds::core::InstanceHandle& handle);

        /**
         * Set DataState to filter with during the read or take.
         *
         * <i>Convenience Functor:</i> dds::sub::state
         *
         * <i>Example</i><br>
         * Read only new data.
         * @code{.cpp}
         * // DataState to filter only new data
         * dds::sub::status::DataState newData = dds::sub::status::DataState::new_data();
         *
         * // Implicit use of ManipulatorSelector
         * reader >> dds::sub::state(newData) >> samples;
         *
         * // Explicit use of ManipulatorSelector
         * dds::sub::DataReader<Foo::Bar>::ManipulatorSelector selectiveReader(reader);
         * selectiveReader.state(newData);
         * selectiveReader.read() >> samples;
         * @endcode
         * See also @link dds::sub::DataReader::operator>>(dds::sub::LoanedSamples<T>& ls)
         * DataReader stream operator>> @endlink
         *
         * @param state the required DataState of the samples
         */
        ManipulatorSelector& state(const dds::sub::status::DataState& state);

        /**
         * Set Query to filter with during the read or take.
         *
         * <i>Convenience Functor:</i> dds::sub::content
         *
         * <i>Example</i><br>
         * Read only samples that will be filtered according to the given dds::sub::Query.
         * @code{.cpp}
         * // Assume data type has an element called long_1
         * dds::sub::Query query(reader, "long_1 > 1 and long_1 < 7");
         *
         * // Implicit use of ManipulatorSelector
         * reader >> dds::sub::content(query) >> samples;
         *
         * // Explicit use of ManipulatorSelector
         * dds::sub::DataReader<Foo::Bar>::ManipulatorSelector selectiveReader(reader);
         * selectiveReader.content(query);
         * selectiveReader >> read;
         * @endcode
         * See also @link dds::sub::DataReader::operator>>(dds::sub::LoanedSamples<T>& ls)
         * DataReader stream operator>> @endlink
         *
         * @param query The Query to apply to a read/take
         */
        ManipulatorSelector& content(const dds::sub::Query& query);

        /**
         * This operation works the same as the @link dds::sub::DataReader::operator>>(dds::sub::LoanedSamples<T>& ls)
         * DataReader stream operator>> @endlink, except that it is performed on this ManipulatorSelector
         * with possible filters set.
         *
         * @throws dds::core::Error
         *                  An internal error has occurred.
         * @throws dds::core::NullReferenceError
         *                  The entity was not properly created and references to dds::core::null.
         * @throws dds::core::AlreadyClosedError
         *                  The entity has already been closed.
         * @throws dds::core::OutOfResourcesError
         *                  The Data Distribution Service ran out of resources to
         *                  complete this operation.
         * @throws dds::core::NotEnabledError
         *                  The DataReader has not yet been enabled.
         */
        ManipulatorSelector&
        operator >>(dds::sub::LoanedSamples<T>& samples);

        /**
         * This operation works the same as the @link dds::sub::DataReader::operator>>(dds::sub::LoanedSamples<T>& ls)
         * DataReader stream operator>> @endlink, except that it is performed on this ManipulatorSelector
         * with possible filters set.
         *
         * @throws dds::core::Error
         *                  An internal error has occurred.
         * @throws dds::core::NullReferenceError
         *                  The entity was not properly created and references to dds::core::null.
         * @throws dds::core::AlreadyClosedError
         *                  The entity has already been closed.
         * @throws dds::core::OutOfResourcesError
         *                  The Data Distribution Service ran out of resources to
         *                  complete this operation.
         * @throws dds::core::NotEnabledError
         *                  The DataReader has not yet been enabled.
         */
        ManipulatorSelector&
        operator >> (ManipulatorSelector & (manipulator)(ManipulatorSelector&));

        /**
         * This operation works the same as the @link dds::sub::DataReader::operator>>(dds::sub::LoanedSamples<T>& ls)
         * DataReader stream operator>> @endlink, except that it is performed on this ManipulatorSelector
         * with possible filters set.
         *
         * @throws dds::core::Error
         *                  An internal error has occurred.
         * @throws dds::core::NullReferenceError
         *                  The entity was not properly created and references to dds::core::null.
         * @throws dds::core::AlreadyClosedError
         *                  The entity has already been closed.
         * @throws dds::core::OutOfResourcesError
         *                  The Data Distribution Service ran out of resources to
         *                  complete this operation.
         * @throws dds::core::NotEnabledError
         *                  The DataReader has not yet been enabled.
         */
        template <typename Functor>
        ManipulatorSelector
        operator >> (Functor f);

    private:
        typename DELEGATE<T>::ManipulatorSelector impl_;

    };

public:
    OMG_DDS_REF_TYPE_PROTECTED_DC_T(DataReader, dds::sub::TAnyDataReader, T, DELEGATE)
    OMG_DDS_IMPLICIT_REF_BASE(DataReader)
    OMG_DDS_COMPLETE_RULE_OF_FIVE_VIRTUAL_DEFAULT(DataReader)

public:
    /**
     * Create a new DataReader for the desired Topic, ContentFilteredTopic or MultiTopic,
     * using the given Subscriber.
     *
     * <i>QoS</i><br>
     * The DataReader will be created with the QoS values specified on the last
     * successful call to @link dds::sub::Subscriber::default_datareader_qos(const dds::sub::qos::DataReaderQos& qos)
     * sub.default_datareader_qos(qos) @endlink or, if the call was never made,
     * the @ref anchor_dds_sub_datareader_qos_defaults "default" values.
     *
     * @param sub       the Subscriber that will contain this DataReader
     * @param topic     the Topic associated with this DataReader
     * @throws dds::core::Error
     *                  An internal error has occurred.
     * @throws dds::core::OutOfResourcesError
     *                  The Data Distribution Service ran out of resources to
     *                  complete this operation.
     */
    DataReader(const dds::sub::Subscriber& sub,
               const ::dds::topic::Topic<T>& topic);

    /**
     * Create a new DataReader for the desired Topic, ContentFilteredTopic or MultiTopic,
     * using the given Subscriber and DataReaderQos and attaches the optionally specified
     * DataReaderListener to it.
     *
     * <i>QoS</i><br>
     * A possible application pattern to construct the DataReaderQos for the
     * DataReader is to:
     * @code{.cpp}
     * // 1) Retrieve the QosPolicy settings on the associated Topic
     * dds::topic::qos::TopicQos topicQos = topic.qos();
     * // 2) Retrieve the default DataReaderQos from the related Subscriber
     * dds::sub::qos::DataReaderQos readerQos = subscriber.default_datareader_qos();
     * // 3) Combine those two lists of QosPolicy settings by overwriting DataReaderQos
     * //    policies that are also present TopicQos
     * readerQos = topicQos;
     * // 4) Selectively modify QosPolicy settings as desired.
     * readerQos << dds::core::policy::Durability::Transient();
     * // 5) Use the resulting QoS to construct the DataReader.
     * dds::sub::DataReader<Foo::Bar> reader(subscriber, topic, readerQos);
     * @endcode
     *
     * <i>Listener</i><br>
     * The following statuses are applicable to the DataReaderListener:
     *  - dds::core::status::StatusMask::requested_deadline_missed()
     *  - dds::core::status::StatusMask::requested_incompatible_qos()
     *  - dds::core::status::StatusMask::sample_lost()
     *  - dds::core::status::StatusMask::sample_rejected()
     *  - dds::core::status::StatusMask::data_available()
     *  - dds::core::status::StatusMask::liveliness_changed()
     *  - dds::core::status::StatusMask::subscription_matched()
     *
     * See @ref DCPS_Modules_Infrastructure_Listener "listener concept",
     * @ref anchor_dds_sub_datareader_commstatus "communication status" and
     * @ref anchor_dds_sub_datareader_commpropagation "communication propagation"
     * for more information.
     *
     * @param sub       the Subscriber that will contain this DataReader
     * @param topic     the Topic, ContentFilteredTopic or MultiTopic associated with this DataReader
     * @param qos       the DataReader qos.
     * @param listener  the DataReader listener.
     * @param mask      the listener event mask.
     * @throws dds::core::Error
     *                  An internal error has occurred.
     * @throws dds::core::OutOfResourcesError
     *                  The Data Distribution Service ran out of resources to
     *                  complete this operation.
     * @throws dds::core::InconsistentPolicyError
     *                  The parameter qos contains conflicting QosPolicy settings.
     */
    DataReader(const dds::sub::Subscriber& sub,
               const ::dds::topic::Topic<T>& topic,
               const dds::sub::qos::DataReaderQos& qos,
               dds::sub::DataReaderListener<T>* listener = NULL,
               const dds::core::status::StatusMask& mask = ::dds::core::status::StatusMask::none());

    #ifdef OMG_DDS_CONTENT_SUBSCRIPTION_SUPPORT

    /** @copydoc dds::sub::DataReader::DataReader(const dds::sub::Subscriber& sub, const ::dds::topic::Topic<T>& topic) */
    DataReader(const dds::sub::Subscriber& sub,
               const ::dds::topic::ContentFilteredTopic<T>& topic);

    /** @copydoc dds::sub::DataReader::DataReader(const dds::sub::Subscriber& sub, const ::dds::topic::Topic<T>& topic, const dds::sub::qos::DataReaderQos& qos, dds::sub::DataReaderListener<T>* listener, const dds::core::status::StatusMask& mask) */
    DataReader(const dds::sub::Subscriber& sub,
               const ::dds::topic::ContentFilteredTopic<T>& topic,
               const dds::sub::qos::DataReaderQos& qos,
               dds::sub::DataReaderListener<T>* listener = NULL,
               const dds::core::status::StatusMask& mask = ::dds::core::status::StatusMask::none());
    #endif /* OMG_DDS_CONTENT_SUBSCRIPTION_SUPPORT */

    #ifdef OMG_DDS_MULTI_TOPIC_SUPPORT

    /** @copydoc dds::sub::DataReader::DataReader(const dds::sub::Subscriber& sub, const ::dds::topic::Topic<T>& topic) */
    DataReader(const dds::sub::Subscriber& sub,
               const ::dds::topic::MultiTopic<T>& topic);

    /** @copydoc dds::sub::DataReader::DataReader(const dds::sub::Subscriber& sub, const ::dds::topic::Topic<T>& topic, const dds::sub::qos::DataReaderQos& qos, dds::sub::DataReaderListener<T>* listener, const dds::core::status::StatusMask& mask) */
    DataReader(const dds::sub::Subscriber& sub,
               const ::dds::topic::MultiTopic<T>& topic,
               const dds::sub::qos::DataReaderQos& qos,
               dds::sub::DataReaderListener<T>* listener = NULL,
               const dds::core::status::StatusMask& mask = ::dds::core::status::StatusMask::none());

    #endif /* OMG_DDS_MULTI_TOPIC_SUPPORT */

public:
    // == ReadState Management

    /**
     * Returns the @ref anchor_dds_sub_datareader_defaultstatefilter "default state filter"
     * for read/take operations.
     *
     * The default value of default_filter_state is dds::sub::status::DataState::any().
     *
     * @return the default state to filter for
     */
     dds::sub::status::DataState default_filter_state();

    /**
     * Set the default state filter for read/take operations.
     *
     * @anchor anchor_dds_sub_datareader_defaultstatefilter
     * <i>Default State Filter</i><br>
     * The default_filter_state indicates what the dds::sub::status::DataState of samples
     * should be for the read to filter them out of the total data samples pool.
     *
     * This filter can be overruled by using dds::sub::DataReader::Selector::state or
     * dds::sub::DataReader::ManipulatorSelector::state during the actual read action.
     *
     * @param state the state mask that will be used to read/take samples
     */
    DataReader& default_filter_state(const dds::sub::status::DataState& state);

    //== Streaming read/take

    /**
     * This operation reads a sequence of typed samples from the DataReader by means
     * of the shift operator.
     *
     * What samples are read depends on what @link dds::sub::DataReader::default_filter_state(const dds::sub::status::DataState& state)
     * default state filter @endlink has been set (default any).
     *
     * This operation reads a sequence of typed samples from the DataReader<type>. The
     * data is put into a dds::sub::LoanedSamples, which is basically a sequence of samples,
     * which in turn contains the actual data and meta information.
     *
     * The memory used for storing the sample may be loaned by the middleware thus allowing zero
     * copy operations.
     *
     * If the DataReader has no samples that meet the constraints, the resulting
     * dds::sub::LoanedSamples will be empty.
     * @code{.cpp}
     * dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
     * dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");
     * dds::sub::Subscriber subscriber(participant);
     * dds::sub::DataReader<Foo::Bar> reader(subscriber, topic);
     *
     * {
     *     dds::sub::LoanedSamples<Foo::Bar> samples;
     *     reader >> samples;
     * }
     * // The LoanedSamples went out of scope, meaning the loan was returned.
     * @endcode
     *
     * <b><i>Take</i></b><br>
     * The default behaviour of the DataReader stream operator>> is to read samples. It can be
     * explicitly stated if the operator should do a read or take.
     * @code{.cpp}
     * reader >> dds::sub::read >> samples;
     * reader >> dds::sub::take >> samples;
     * @endcode
     * These are two of the available convenience manipulators (see next paragraph).
     *
     * <b><i>Manipulators</i></b><br>
     * Manipulators are defined externally to make it possible to control which data is read
     * and whether the streaming operators reads or takes.
     *
     * Available convenience stream manipulators:
     * - dds::sub::read
     * - dds::sub::take
     * - dds::sub::max_samples
     * - dds::sub::content
     * - dds::sub::state
     * - dds::sub::instance
     * - dds::sub::next_instance
     *
     * The manipulators can be concatenated:
     * @code{.cpp}
     * // Take (iso read) a maximum of 3 new samples of a certain instance.
     * reader >> dds::sub::take
     *        >> dds::sub::max_samples(3)
     *        >> dds::sub::state(dds::sub::status::DataState::new_data())
     *        >> dds::sub::instance(someValidInstanceHandle)
     *        >> samples;
     * @endcode
     *
     * <i>Please be aware that using pre-set filters on the DataReader and then
     * call read() or take() on that reader explicitly will perform better than
     * having to create Manipulators for every read (which is what essentially
     * happens in the code example above). Performance can be increase by creating
     * a manipulator up front and using that multiple times
     * (see dds::sub::DataReader::ManipulatorSelector).</i>
     *
     * <b><i>Invalid Data</i></b><br>
     * Some elements in the returned sequence may not have valid data: the valid_data
     * field in the SampleInfo indicates whether the corresponding data value contains
     * any meaningful data. If not, the data value is just a ‘dummy’ sample for which only
     * the keyfields have been assigned. It is used to accompany the SampleInfo that
     * communicates a change in the instance_state of an instance for which there is
     * no ‘real’ sample available.
     *
     * For example, when an application always ‘takes’ all available samples of a
     * particular instance, there is no sample available to report the disposal of that
     * instance. In such a case the DataReader will insert a dummy sample into the
     * data_values sequence to accompany the SampleInfo element in the info_seq
     * sequence that communicates the disposal of the instance.
     *
     * The act of reading a sample sets its sample_state to READ_SAMPLE_STATE. If
     * the sample belongs to the most recent generation of the instance, it also sets the
     * view_state of the instance to NOT_NEW_VIEW_STATE. It does not affect the
     * instance_state of the instance.
     *
     * @throws dds::core::Error
     *                  An internal error has occurred.
     * @throws dds::core::NullReferenceError
     *                  The entity was not properly created and references to dds::core::null.
     * @throws dds::core::AlreadyClosedError
     *                  The entity has already been closed.
     * @throws dds::core::OutOfResourcesError
     *                  The Data Distribution Service ran out of resources to
     *                  complete this operation.
     * @throws dds::core::NotEnabledError
     *                  The DataReader has not yet been enabled.
     */
    DataReader& operator>>(dds::sub::LoanedSamples<T>& ls);

    /** @copydoc dds::sub::DataReader::operator>>(dds::sub::LoanedSamples<T>& ls) */
    ManipulatorSelector
    operator>> (ManipulatorSelector & (manipulator)(ManipulatorSelector&));

    /** @copydoc dds::sub::DataReader::operator>>(dds::sub::LoanedSamples<T>& ls) */
    template <typename Functor>
    ManipulatorSelector
    operator>> (Functor f);


    ///////////////////////////////////////////////////////////////////////
public:
    //== Loan Read/Take API ==================================================

    /**
     * This operation reads a sequence of typed samples from the DataReader.
     *
     * What samples are read depends on what @link dds::sub::DataReader::default_filter_state(const dds::sub::status::DataState& state)
     * default state filter @endlink has been set (default any).
     *
     * This operation reads a sequence of typed samples from the DataReader<type>. The
     * data is put into a dds::sub::LoanedSamples, which is basically a sequence of samples,
     * which in turn contains the actual data and meta information.
     *
     * The memory used for storing the sample may be loaned by the middleware thus allowing zero
     * copy operations.
     *
     * If the DataReader has no samples that meet the constraints, the resulting
     * dds::sub::LoanedSamples will be empty.
     * @code{.cpp}
     * dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
     * dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");
     * dds::sub::Subscriber subscriber(participant);
     * dds::sub::DataReader<Foo::Bar> reader(subscriber, topic);
     *
     * {
     *     // Read the available samples.
     *     dds::sub::LoanedSamples<Foo::Bar> samples;
     *     samples = reader.read();
     *
     *     // Access the information.
     *     dds::sub::LoanedSamples<Foo::Bar>::const_iterator it;
     *     for (it = samples.begin(); it != samples.end(); ++it) {
     *         const dds::sub::Sample<Foo::Bar>& sample = *it;
     *     }
     * }
     * // The LoanedSamples went out of scope, meaning the loan resources were taken care of.
     * @endcode
     *
     * <b><i>Selectors</i></b><br>
     * What data is read already depends on the
     * @ref anchor_dds_sub_datareader_defaultstatefilter "default state filter".
     * But it can be manipulated even more when using dds::sub::DataReader::select()
     * operation.
     *
     * @anchor anchor_dds_sub_datareader_invalidsamples
     * <b><i>Invalid Data</i></b><br>
     * Some elements in the returned sequence may not have valid data: the valid_data
     * field in the SampleInfo indicates whether the corresponding data value contains
     * any meaningful data. If not, the data value is just a ‘dummy’ sample for which only
     * the keyfields have been assigned. It is used to accompany the SampleInfo that
     * communicates a change in the instance_state of an instance for which there is
     * no ‘real’ sample available.
     *
     * For example, when an application always ‘takes’ all available samples of a
     * particular instance, there is no sample available to report the disposal of that
     * instance. In such a case the DataReader will insert a dummy sample into the
     * data_values sequence to accompany the SampleInfo element in the info_seq
     * sequence that communicates the disposal of the instance.
     *
     * The act of reading a sample sets its sample_state to READ_SAMPLE_STATE. If
     * the sample belongs to the most recent generation of the instance, it also sets the
     * view_state of the instance to NOT_NEW_VIEW_STATE. It does not affect the
     * instance_state of the instance.
     *
     * @return          The samples in the LoanedSamples container
     * @throws dds::core::Error
     *                  An internal error has occurred.
     * @throws dds::core::NullReferenceError
     *                  The entity was not properly created and references to dds::core::null.
     * @throws dds::core::AlreadyClosedError
     *                  The entity has already been closed.
     * @throws dds::core::OutOfResourcesError
     *                  The Data Distribution Service ran out of resources to
     *                  complete this operation.
     * @throws dds::core::NotEnabledError
     *                  The DataReader has not yet been enabled.
     */
    LoanedSamples<T> read();

    /**
     * This operation takes a sequence of typed samples from the DataReader.
     *
     * The behaviour is identical to read except for that the samples are removed
     * from the DataReader.
     *
     * What samples are taken depends on what @link dds::sub::DataReader::default_filter_state(const dds::sub::status::DataState& state)
     * default state filter @endlink has been set (default any).
     *
     * This operation takes a sequence of typed samples from the DataReader<type>. The
     * data is put into a dds::sub::LoanedSamples, which is basically a sequence of samples,
     * which in turn contains the actual data and meta information.
     *
     * The memory used for storing the sample may be loaned by the middleware thus allowing zero
     * copy operations.
     *
     * If the DataReader has no samples that meet the constraints, the resulting
     * dds::sub::LoanedSamples will be empty.
     * @code{.cpp}
     * dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
     * dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");
     * dds::sub::Subscriber subscriber(participant);
     * dds::sub::DataReader<Foo::Bar> reader(subscriber, topic);
     *
     * {
     *     // Take the available samples.
     *     dds::sub::LoanedSamples<Foo::Bar> samples;
     *     samples = reader.take();
     *
     *     // Access the information.
     *     dds::sub::LoanedSamples<Foo::Bar>::const_iterator it;
     *     for (it = samples.begin(); it != samples.end(); ++it) {
     *         const dds::sub::Sample<Foo::Bar>& sample = *it;
     *     }
     * }
     * // The LoanedSamples went out of scope, meaning the loan resources were taken care of.
     * @endcode
     *
     * <b><i>Selectors</i></b><br>
     * What data is taken, already depends on the
     * @ref anchor_dds_sub_datareader_defaultstatefilter "default state filter".
     * But it can be manipulated even more when using dds::sub::DataReader::select()
     * operation.
     *
     * <b><i>Invalid Data</i></b><br>
     * Some elements in the returned sequence may not have valid data: the valid_data
     * field in the SampleInfo indicates whether the corresponding data value contains
     * any meaningful data.<br>
     * Look @ref anchor_dds_sub_datareader_invalidsamples "here" for more information.
     *
     * @return          The samples in the LoanedSamples container
     * @throws dds::core::Error
     *                  An internal error has occurred.
     * @throws dds::core::NullReferenceError
     *                  The entity was not properly created and references to dds::core::null.
     * @throws dds::core::AlreadyClosedError
     *                  The entity has already been closed.
     * @throws dds::core::OutOfResourcesError
     *                  The Data Distribution Service ran out of resources to
     *                  complete this operation.
     * @throws dds::core::NotEnabledError
     *                  The DataReader has not yet been enabled.
     */
    LoanedSamples<T> take();

    //== Copy Read/Take API ==================================================

    // --- Forward Iterators: --- //

    /**
     * This operation reads a sequence of typed samples from the DataReader.
     *
     * What samples are read depends on what @link dds::sub::DataReader::default_filter_state(const dds::sub::status::DataState& state)
     * default state filter @endlink has been set (default any).
     *
     * The samples are copied into the application provided container using the
     * forward iterator parameter.
     *
     * If the DataReader has no samples that meet the constraints, the resulting
     * dds::sub::LoanedSamples will be empty.
     * @code{.cpp}
     * dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
     * dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");
     * dds::sub::Subscriber subscriber(participant);
     * dds::sub::DataReader<Foo::Bar> reader(subscriber, topic);
     *
     * // Prepare container to store samples in
     * const uint32_t MAX_SAMPLES (3)
     * std::vector<dds::sub::Sample<Foo::Bar> > samples(MAX_SAMPLES);
     * std::vector<dds::sub::Sample<Foo::Bar> >::iterator iter = samples.begin();
     *
     * // Read and copy the available samples into the vector by means of the iterator
     * uint32_t len =  reader.read(iter, MAX_SAMPLES);
     *
     * // Access the information.
     * for (iter = samples.begin(); iter != samples.end(); ++iter) {
     *     const dds::sub::Sample<Foo::Bar>& sample = *iter;
     * }
     * @endcode
     *
     * <b><i>Selectors</i></b><br>
     * What data is read already depends on the
     * @ref anchor_dds_sub_datareader_defaultstatefilter "default state filter".
     * But it can be manipulated even more when using dds::sub::DataReader::select()
     * operation.
     *
     * <b><i>Invalid Data</i></b><br>
     * Some elements in the returned sequence may not have valid data: the valid_data
     * field in the SampleInfo indicates whether the corresponding data value contains
     * any meaningful data.<br>
     * Look @ref anchor_dds_sub_datareader_invalidsamples "here" for more information.
     *
     * @param  sfit     Forward-inserting container iterator
     * @param  max_samples Maximum samples to read and copy into the given container
     * @return          The number of samples in the LoanedSamples container
     * @throws dds::core::Error
     *                  An internal error has occurred.
     * @throws dds::core::NullReferenceError
     *                  The entity was not properly created and references to dds::core::null.
     * @throws dds::core::AlreadyClosedError
     *                  The entity has already been closed.
     * @throws dds::core::OutOfResourcesError
     *                  The Data Distribution Service ran out of resources to
     *                  complete this operation.
     * @throws dds::core::NotEnabledError
     *                  The DataReader has not yet been enabled.
     */
    template <typename SamplesFWIterator>
    uint32_t
    read(SamplesFWIterator sfit,
         uint32_t max_samples);

    /**
     * This operation takes a sequence of typed samples from the DataReader.
     *
     * What samples are take depends on what @link dds::sub::DataReader::default_filter_state(const dds::sub::status::DataState& state)
     * default state filter @endlink has been set (default any).
     *
     * The samples are copied into the application provided container using the
     * forward iterator parameter.
     *
     * If the DataReader has no samples that meet the constraints, the resulting
     * dds::sub::LoanedSamples will be empty.
     * @code{.cpp}
     * dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
     * dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");
     * dds::sub::Subscriber subscriber(participant);
     * dds::sub::DataReader<Foo::Bar> reader(subscriber, topic);
     *
     * // Prepare container to store samples in
     * const uint32_t MAX_SAMPLES (3)
     * std::vector<dds::sub::Sample<Foo::Bar> > samples(MAX_SAMPLES);
     * std::vector<dds::sub::Sample<Foo::Bar> >::iterator iter = samples.begin();
     *
     * // Take and copy the available samples into the vector by means of the iterator
     * uint32_t len =  reader.take(iter, MAX_SAMPLES);
     *
     * // Access the information.
     * for (iter = samples.begin(); iter != samples.end(); ++iter) {
     *     const dds::sub::Sample<Foo::Bar>& sample = *iter;
     * }
     * @endcode
     *
     * <b><i>Selectors</i></b><br>
     * What data is taken, already depends on the
     * @ref anchor_dds_sub_datareader_defaultstatefilter "default state filter".
     * But it can be manipulated even more when using dds::sub::DataReader::select()
     * operation.
     *
     * <b><i>Invalid Data</i></b><br>
     * Some elements in the returned sequence may not have valid data: the valid_data
     * field in the SampleInfo indicates whether the corresponding data value contains
     * any meaningful data.<br>
     * Look @ref anchor_dds_sub_datareader_invalidsamples "here" for more information.
     *
     * @param  sfit     Forward-inserting container iterator
     * @param  max_samples Maximum samples to take and copy into the given container
     * @return          The number of samples in the given container
     * @throws dds::core::Error
     *                  An internal error has occurred.
     * @throws dds::core::NullReferenceError
     *                  The entity was not properly created and references to dds::core::null.
     * @throws dds::core::AlreadyClosedError
     *                  The entity has already been closed.
     * @throws dds::core::OutOfResourcesError
     *                  The Data Distribution Service ran out of resources to
     *                  complete this operation.
     * @throws dds::core::NotEnabledError
     *                  The DataReader has not yet been enabled.
     */
    template <typename SamplesFWIterator>
    uint32_t
    take(SamplesFWIterator sfit,
         uint32_t max_samples);


    // --- Back-Inserting Iterators: --- //

    /**
     * This operation reads a sequence of typed samples from the DataReader.
     *
     * What samples are read depends on what @link dds::sub::DataReader::default_filter_state(const dds::sub::status::DataState& state)
     * default state filter @endlink has been set (default any).
     *
     * The samples are copied into the application provided container using a
     * back-inserting iterator. Notice that as a consequence of using a back-inserting
     * iterator, this operation may allocate memory to resize the underlying container.
     *
     * If the DataReader has no samples that meet the constraints, the resulting
     * dds::sub::LoanedSamples will be empty.
     * @code{.cpp}
     * dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
     * dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");
     * dds::sub::Subscriber subscriber(participant);
     * dds::sub::DataReader<Foo::Bar> reader(subscriber, topic);
     *
     * // Prepare container to store samples in
     * std::vector<dds::sub::Sample<Foo::Bar> > samples;
     * std::back_insert_iterator< std::vector<dds::sub::Sample<Foo::Bar> > > bi(samples);
     *
     * // Read and copy the available samples into the vector by means of the iterator
     * uint32_t len =  reader.read(bi);
     *
     * // Access the information.
     * std::vector<dds::sub::Sample<Space::Type1> >::iterator iter = samples.begin();
     * for (iter = samples.begin(); iter != samples.end(); ++iter) {
     *     const dds::sub::Sample<Foo::Bar>& sample = *iter;
     * }
     * @endcode
     *
     * <b><i>Selectors</i></b><br>
     * What data is read already depends on the
     * @ref anchor_dds_sub_datareader_defaultstatefilter "default state filter".
     * But it can be manipulated even more when using dds::sub::DataReader::select()
     * operation.
     *
     * <b><i>Invalid Data</i></b><br>
     * Some elements in the returned sequence may not have valid data: the valid_data
     * field in the SampleInfo indicates whether the corresponding data value contains
     * any meaningful data.<br>
     * Look @ref anchor_dds_sub_datareader_invalidsamples "here" for more information.
     *
     * @param  sbit     Back-inserting container iterator
     * @return          The number of samples in the given container
     * @throws dds::core::Error
     *                  An internal error has occurred.
     * @throws dds::core::NullReferenceError
     *                  The entity was not properly created and references to dds::core::null.
     * @throws dds::core::AlreadyClosedError
     *                  The entity has already been closed.
     * @throws dds::core::OutOfResourcesError
     *                  The Data Distribution Service ran out of resources to
     *                  complete this operation.
     * @throws dds::core::NotEnabledError
     *                  The DataReader has not yet been enabled.
     */
    template <typename SamplesBIIterator>
    uint32_t
    read(SamplesBIIterator sbit);

    /**
     * This operation takes a sequence of typed samples from the DataReader.
     *
     * What samples are take depends on what @link dds::sub::DataReader::default_filter_state(const dds::sub::status::DataState& state)
     * default state filter @endlink has been set (default any).
     *
     * The samples are copied into the application provided container using a
     * back-inserting iterator. Notice that as a consequence of using a back-inserting
     * iterator, this operation may allocate memory to resize the underlying container.
     *
     * If the DataReader has no samples that meet the constraints, the resulting
     * dds::sub::LoanedSamples will be empty.
     * @code{.cpp}
     * dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
     * dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");
     * dds::sub::Subscriber subscriber(participant);
     * dds::sub::DataReader<Foo::Bar> reader(subscriber, topic);
     *
     * // Prepare container to store samples in
     * std::vector<dds::sub::Sample<Foo::Bar> > samples;
     * std::back_insert_iterator< std::vector<dds::sub::Sample<Foo::Bar> > > bi(samples);
     *
     * // Take and copy the available samples into the vector by means of the iterator
     * uint32_t len =  reader.take(bi);
     *
     * // Access the information.
     * std::vector<dds::sub::Sample<Space::Type1> >::iterator iter = samples.begin();
     * for (iter = samples.begin(); iter != samples.end(); ++iter) {
     *     const dds::sub::Sample<Foo::Bar>& sample = *iter;
     * }
     * @endcode
     *
     * <b><i>Selectors</i></b><br>
     * What data is taken, already depends on the
     * @ref anchor_dds_sub_datareader_defaultstatefilter "default state filter".
     * But it can be manipulated even more when using dds::sub::DataReader::select()
     * operation.
     *
     * <b><i>Invalid Data</i></b><br>
     * Some elements in the returned sequence may not have valid data: the valid_data
     * field in the SampleInfo indicates whether the corresponding data value contains
     * any meaningful data.<br>
     * Look @ref anchor_dds_sub_datareader_invalidsamples "here" for more information.
     *
     * @param  sbit     Back-inserting container iterator
     * @return          The number of samples in the given container
     * @throws dds::core::Error
     *                  An internal error has occurred.
     * @throws dds::core::NullReferenceError
     *                  The entity was not properly created and references to dds::core::null.
     * @throws dds::core::AlreadyClosedError
     *                  The entity has already been closed.
     * @throws dds::core::OutOfResourcesError
     *                  The Data Distribution Service ran out of resources to
     *                  complete this operation.
     * @throws dds::core::NotEnabledError
     *                  The DataReader has not yet been enabled.
     */
    template <typename SamplesBIIterator>
    uint32_t
    take(SamplesBIIterator sbit);
public:
    //========================================================================
    //== DSL Method for dealing with instances, content and status filters.

    /**
     * Get a dds::sub::DataReader::Selector instance that acts on this DataReader.
     *
     * The DataReader::read and DataReader::take read all samples that are
     * available within the DataReader (provided that the
     * @ref anchor_dds_sub_datareader_defaultstatefilter "default state filter"
     * hasn't been changed).
     *
     * <b><i>Selectors</i></b><br>
     * A Selector can perform complex data selections, such as per-instance selection,
     * content and status filtering, etc when reading or taking. Such a selector is
     * returned by this operation. Setting filters on the Selector can be concatenated,
     * resulting in the following example code.
     * @code{.cpp}
     * dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
     * dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");
     * dds::sub::Subscriber subscriber(participant);
     * dds::sub::DataReader<Foo::Bar> reader(subscriber, topic);
     *
     * // Take a maximum of 3 new samples of a certain instance.
     * {
     *     dds::sub::LoanedSamples<Foo::Bar> samples;
     *     samples = reader.select()
     *                         .max_samples(3)
     *                         .state(dds::sub::status::DataState::new_data())
     *                         .instance(someValidInstanceHandle)
     *                         .take();
     * }
     * @endcode
     *
     * <i>Please be aware that using pre-set filters on the DataReader and then
     * call read() or take() on that reader explicitly will perform better than
     * having to create Selectors for every read (which is what essentially
     * happens in the code example above). Performance can be increase by creating
     * a selector up front and using that multiple times
     * (see dds::sub::DataReader::Selector).</i>
     *
     * @return          A Selector that acts on the DataReader
     * @throws dds::core::Error
     *                  An internal error has occurred.
     * @throws dds::core::NullReferenceError
     *                  The entity was not properly created and references to dds::core::null.
     * @throws dds::core::AlreadyClosedError
     *                  The entity has already been closed.
     * @throws dds::core::OutOfResourcesError
     *                  The Data Distribution Service ran out of resources to
     *                  complete this operation.
     * @throws dds::core::NotEnabledError
     *                  The DataReader has not yet been enabled.
     */
    Selector select();

    //========================================================================
    //== Instance Management
public:
    /**
     * This operation retrieves the key value of a specific instance.
     *
     * This operation can be used to retrieve the instance key that corresponds
     * to an instance_handle. The operation will only fill the fields that form
     * the key inside the sample instance.
     *
     * This operation may raise a InvalidArgumentError exception if the InstanceHandle
     * does not correspond to an existing data-object known to the DataReader.
     * If the implementation is not able to check invalid handles, then the
     * result in this situation is unspecified.
     *
     * @param  h        The instance handle
     * @return          A topic instance with the handle and key fields set
     * @throws dds::core::Error
     *                  An internal error has occurred.
     * @throws dds::core::InvalidArgumentError
     *                  The InstanceHandle is not a valid handle.
     * @throws dds::core::AlreadyClosedError
     *                  The entity has already been closed.
     * @throws dds::core::OutOfResourcesError
     *                  The Data Distribution Service ran out of resources to
     *                  complete this operation.
     * @throws dds::core::NotEnabledError
     *                  The DataReader has not yet been enabled.
     * @throws dds::core::PreconditionNotMetError
     *                  The handle has not been registered with this DataReader.
     */
    dds::topic::TopicInstance<T> key_value(const dds::core::InstanceHandle& h);

    /**
     * This operation retrieves the key value of a specific instance.
     *
     * This operation can be used to retrieve the instance key that corresponds
     * to an instance_handle. The operation will only fill the fields that form
     * the key inside the sample instance.
     *
     * This operation may raise a InvalidArgumentError exception if the InstanceHandle
     * does not correspond to an existing data-object known to the DataReader.
     * If the implementation is not able to check invalid handles, then the
     * result in this situation is unspecified.
     *
     * The Sample is added as parameter to be able to overload this operation.
     *
     * @param[out] sample A sample to set the key fields of
     * @param[in] h     The instance handle
     * @return          The given sample with the key fields set
     * @throws dds::core::Error
     *                  An internal error has occurred.
     * @throws dds::core::InvalidArgumentError
     *                  The InstanceHandle is not a valid handle.
     * @throws dds::core::AlreadyClosedError
     *                  The entity has already been closed.
     * @throws dds::core::OutOfResourcesError
     *                  The Data Distribution Service ran out of resources to
     *                  complete this operation.
     * @throws dds::core::NotEnabledError
     *                  The DataReader has not yet been enabled.
     * @throws dds::core::PreconditionNotMetError
     *                  The handle has not been registered with this DataReader.
     */
    T& key_value(T& sample, const dds::core::InstanceHandle& h);

    /**
     * This operation returns the value of the instance handle which corresponds
     * to the instance_data.
     *
     * The instance handle can be used in read operations that operate
     * on a specific instance. Note that DataReader instance handles are local, and are
     * not interchangeable with DataWriter instance handles nor with instance handles
     * of an other DataReader.
     *
     * This operation does not register the instance in question. If the instance has not been
     * previously registered or if for any other
     * reason the Service is unable to provide an instance handle, the Service will return
     * the default nil handle (InstanceHandle.is_nil() == true).
     *
     * @param key the sample
     * @return the instance handle
     * @throws dds::core::NullReferenceError
     *                  The entity was not properly created and references to dds::core::null.
     * @throws dds::core::AlreadyClosedError
     *                  The entity has already been closed.
     */
    const dds::core::InstanceHandle
    lookup_instance(const T& key) const;

public:

    /**
     * Register a listener with the DataReader.
     *
     * This operation attaches a DataReaderListener to the DataReader. Only one
     * DataReaderListener can be attached to each DataReader. If a
     * DataReaderListener was already attached, the operation will replace it with the
     * new one. When the listener is the NULL pointer, it represents a listener that is
     * treated as a NOOP for all statuses activated in the bit mask.
     *
     * Listener un-registration is performed by setting the listener to NULL and mask none().
     *
     * @anchor anchor_dds_sub_datareader_commstatus
     * <i>Communication Status</i><br>
     * For each communication status, the StatusChangedFlag flag is initially set to
     * FALSE. It becomes TRUE whenever that communication status changes. For each
     * communication status activated in the mask, the associated DataReaderListener
     * operation is invoked and the communication status is reset to FALSE, as the listener
     * implicitly accesses the status which is passed as a parameter to that operation. The
     * status is reset prior to calling the listener, so if the application calls the
     * get_<status_name>_status from inside the listener it will see the status
     * already reset. An exception to this rule is the NULL listener, which does not reset the
     * communication statuses for which it is invoked.
     *
     * The following statuses are applicable to the DataReaderListener:
     *  - dds::core::status::StatusMask::requested_deadline_missed()
     *  - dds::core::status::StatusMask::requested_incompatible_qos()
     *  - dds::core::status::StatusMask::sample_lost()
     *  - dds::core::status::StatusMask::sample_rejected()
     *  - dds::core::status::StatusMask::data_available()
     *  - dds::core::status::StatusMask::liveliness_changed()
     *  - dds::core::status::StatusMask::subscription_matched()
     *
     * Be aware that the SUBSCRIPTION_MATCHED_STATUS is not applicable when the
     * infrastructure does not have the information available to determine connectivity.
     * This is the case when OpenSplice is configured not to maintain discovery
     * information in the Networking Service. (See the description for the
     * NetworkingService/Discovery/enabled property in the Deployment
     * Manual for more information about this subject.) In this case the operation will
     * throw UnsupportedError.
     *
     * Status bits are declared as a constant and can be used by the application in an OR
     * operation to create a tailored mask. The special constant dds::core::status::StatusMask::none()
     * can be used to indicate that the created entity should not respond to any of its available
     * statuses. The DDS will therefore attempt to propagate these statuses to its factory.
     * The special constant dds::core::status::StatusMask::all() can be used to select all applicable
     * statuses specified in the "Data Distribution Service for Real-time Systems Version
     * 1.2" specification which are applicable to the PublisherListener.
     *
     * @anchor anchor_dds_sub_datareader_commpropagation
     * <i>Status Propagation</i><br>
     * In case a communication status is not activated in the mask of the
     * DataReaderListener, the SubscriberListener of the containing Subscriber
     * is invoked (if attached and activated for the status that occurred). This allows the
     * application to set a default behaviour in the SubscriberListener of the containing
     * Subscriber and a DataReader specific behaviour when needed. In case the
     * communication status is not activated in the mask of the SubscriberListener as
     * well, the communication status will be propagated to the
     * DomainParticipantListener of the containing DomainParticipant. In case
     * the DomainParticipantListener is also not attached or the communication
     * status is not activated in its mask, the application is not notified of the change.
     *
     * The statuses DATA_ON_READERS_STATUS and DATA_AVAILABLE_STATUS are
     * "Read Communication Statuses" and are an exception to all other plain
     * communication statuses: they have no corresponding status structure that can be
     * obtained with a get_<status_name>_status operation and they are mutually
     * exclusive. When new information becomes available to a DataReader, the Data
     * Distribution Service will first look in an attached and activated
     * SubscriberListener or DomainParticipantListener (in that order) for the
     * DATA_ON_READERS_STATUS. In case the DATA_ON_READERS_STATUS can not be
     * handled, the Data Distribution Service will look in an attached and activated
     * DataReaderListener, SubscriberListener or DomainParticipant
     * Listener for the DATA_AVAILABLE_STATUS (in that order).
     *
     * See also @ref DCPS_Modules_Infrastructure_Listener "listener information".
     *
     * @param listener  the listener
     * @param event_mask the mask defining the events for which the listener
     *                  will be notified.
     * @throws dds::core::Error
     *                  An internal error has occurred.
     * @throws dds::core::NullReferenceError
     *                  The entity was not properly created and references to dds::core::null.
     * @throws dds::core::AlreadyClosedError
     *                  The entity has already been closed.
     * @throws dds::core::UnsupportedError
     *                  A status was selected that cannot be supported because
     *                  the infrastructure does not maintain the required connectivity information.
     * @throws dds::core::OutOfResourcesError
     *                  The Data Distribution Service ran out of resources to
     *                  complete this operation.
     */
    void listener(Listener* listener,
                  const dds::core::status::StatusMask& event_mask);

    /**
     * Get the listener of this DataReader.
     *
     * See also @ref DCPS_Modules_Infrastructure_Listener "listener information".
     *
     * @return the listener
     * @throws dds::core::NullReferenceError
     *                  The entity was not properly created and references to dds::core::null.
     */
    Listener* listener() const;
};


#endif /* OMG_DDS_SUB_TDATA_READER_HPP_ */