#ifndef OMG_DDS_SUB_TCOHERENT_ACCESS_HPP_
#define OMG_DDS_SUB_TCOHERENT_ACCESS_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/Value.hpp>


namespace dds
{
namespace sub
{
template <typename DELEGATE>
class TCoherentAccess;
}
}

/**
 * @brief
 * Class for RAII way of beginning/ending coherent access.
 *
 * Coherent access indicates that the application is about to access
 * the data samples in any of the DataReader objects attached to the
 * Subscriber.
 *
 * The application is required to use this operation
 * only if Presentation QosPolicy of the Subscriber to which the
 * DataReader belongs has the access_scope set to "GROUP". In the
 * aforementioned case, the operation must be called
 * prior to calling any of the sample-accessing operations, i.e.
 * read and take on DataReader. Otherwise the sample-accessing
 * operations will throw a PreconditionNotMetError exception.
 *
 * Once the application has finished accessing the data samples
 * it must end the coherent access. It is not required for the
 * application to begin or end access if the Presentation QosPolicy
 * has the access_scope set to something other than GROUP. Beginning
 * or ending access in this case is not considered an error and has
 * no effect. Beginning and ending access may be nested. In that
 * case, the application end access as many times as it began
 * access.
 *
 * @code{.cpp}
 * dds::domain::DomainParticipant participant(org::eclipse::cyclonedds::domain::default_id());
 * dds::topic::Topic<Foo::Bar> topic(participant, "TopicName");
 *
 * dds::sub::qos::SubscriberQos sQos sQos = participant.default_subscriber_qos()
 *                                          << dds::core::policy::Presentation::TopicAccessScope(false, true);
 * dds::sub::Subscriber subscriber(participant, sQos);
 *
 * {
 *     std::vector< dds::sub::DataReader<Foo::Bar> > readers;
 *     // Start coherent access.
 *     dds::sub::TCoherentAccess coherentAccess(subscriber);
 *     // Find (previously created with the subscriber) datareaders that now got data.
 *     dds::sub::find< dds::sub::DataReader<Foo::Bar> >(subscriber,
 *                                                      dds::sub::status::DataState::any(),
 *                                                      back_inserter(readers));
 *     // Get data from the readers
 *     for (size_type i = 0; i < rv.size(); i++) {
 *         dds::sub::LoanedSamples<Foo::Bar> samples = readers[i].read()
 *         dds::sub::LoanedSamples<Type1>::const_iterator it;
 *         for (it = samples.begin(); it != samples.end(); iterator++) {
 *             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.
 *         }
 *     }
 * }
 * // CoherentAccess went out of scope: it is ended implicitly
 * @endcode
 *
 * @see for more information: @ref DCPS_Modules_Subscription "Subscription"
 * @see dds::sub::Subscriber
 */
template <typename DELEGATE>
class dds::sub::TCoherentAccess : public dds::core::Value<DELEGATE>
{
public:
    /**
     * Creating a CoherentAccess object, which will begin ‘coherent access’ of
     * received samples using DataReader objects attached to this Subscriber.
     *
     * @param sub The Subscriber to begin the coherent access on.
     * @throws dds::core::Error
     *                  An internal error has occurred.
     * @throws dds::core::AlreadyClosedError
     *                  The Subscriber has already been closed.
     * @throws dds::core::NotEnabledError
     *                  The Subscriber has not yet been enabled.
     * @throws dds::core::OutOfResourcesError
     *                  The Data Distribution Service ran out of resources to
     *                  complete this operation.
     * @throws dds::core::NullReferenceError
     *                  The Subscriber was not properly created and references to dds::core::null.
     */
    explicit TCoherentAccess(const dds::sub::Subscriber& sub);

public:
    /**
     * This operation will explicitly end the coherent access.
     *
     * If the Subscriber already ended its coherent access (by a call to this very
     * operation), then a call to this operation will have no effect.
     *
     * @throws dds::core::Error
     *                  An internal error has occurred.
     * @throws dds::core::AlreadyClosedError
     *                  The Subscriber has already been closed.
     * @throws dds::core::NotEnabledError
     *                  The Subscriber has not yet been enabled.
     * @throws dds::core::NullReferenceError
     *                  The Subscriber was not properly created and references to dds::core::null.
     */
    void end();

public:
    /**
     * The destruction of the CoherentAccess will implicitly end the coherent
     * access if not already ended by a call to end().
     *
     * When there is a problem with which end() would normally throw an exception,
     * then that exception is swallowed. Errors can be found in the logs.
     */
    ~TCoherentAccess();

private:
    TCoherentAccess(const TCoherentAccess&);
    TCoherentAccess& operator=(const TCoherentAccess&);
};


#endif /* OMG_TDDS_SUB_TCOHERENT_ACCESS_HPP_ */