/**
 * @file Common/ieventqueue.h
 * @brief Event queue interface
 * @author Enar Vaikene
 *
 * Copyright (c) 2011-2019 Enar Vaikene
 *
 * This file is part of the eVaf C++ cross-platform application development framework.
 *
 * This file can be used under the terms of the GNU General Public License
 * version 3.0 as published by the Free Software Foundation and appearing in
 * the file LICENSE included in the packaging of this file. Please review the
 * the following information to ensure the GNU General Public License version
 * 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
 *
 * Alternatively, this file may be used in accordance with the Commercial License
 * Agreement provided with the Software.
 */

#ifndef __COMMON_IEVENTQUEUE_H
#define __COMMON_IEVENTQUEUE_H

#include "libcommon.h"

#include <QObject>
#include <QString>

namespace eVaf {
namespace Common {

class Event;

/**
 * The eVaf event queue interface
 * @code#include <Common/iEventQueue>@endcode
 *
 * This interface is used to work with eVaf events. Functions in this interface register new events,
 * subscribe to existing events and broadcast events to the rest of the application.
 * Events are implemented using the Qt event loop.
 */
class COMMON_EXPORT iEventQueue : public QObject
{
    Q_OBJECT

public:

    /// Interface constructor
    iEventQueue() : QObject() {}

    /// Empty virtual destructor
    virtual ~iEventQueue() {}

    /**
     * Returns the instance of the iEventQueue interface
     * @return The iEventQueue interface
     */
    static iEventQueue * instance();

    /**
     * Registers an event
     * @param name Name of the event
     * @return Unique ID of the event
     *
     * This function registers an event and returns a unique ID for the event. The event ID value
     * is always greater than zero.
     *
     * If an event with the given name already exists, then returns the event ID for the existing
     * event.
     */
    virtual uint registerEvent(QString const & name) = 0;

    /**
     * Queries for an existing event
     * @param name Name of the event
     * @return The ID of the event or 0 if not found
     *
     * This function returns the ID of the event or zero if no such event is found.
     */
    virtual uint queryEvent(QString const & name) const = 0;

    /**
     * Unregisters an event
     * @param id The ID of the event
     *
     * This function removes an event. It also unsubscribes all the subscribers from this event.
     */
    virtual void unregisterEvent(uint id) = 0;

    /**
     * Subscribes to an event
     * @param id The ID of the event (can be zero)
     * @param obj The subscriber object
     * @return The ID of the event; or zero if failed to subscribe
     *
     * This function subscribes to an event identified by the ID value. Every object that wants to
     * receive specific events, needs to subscribe to them.
     *
     * The id parameter can be zero and the following example code is correct even when the event
     * called "my-event" does not exist. The value of myEventId will be set to zero if the event
     * does not exist.
     * @code
     * int myEventId = iEventQueue::instance()->subscribeEvent(iEventQueue::instance()->queryEvent("my-event"), this);
     * @endcode
     */
    virtual uint subscribeEvent(uint id, QObject * obj) = 0;

    /**
     * Unsubscribes from an event
     * @param id The ID of the event (can be zero)
     * @param obj The subscriber object
     *
     * This function removes the subscriber object from the list of subscribers for the given event identified
     * by the event ID value. After this function call the subscriber does no more receive these events.
     */
    virtual void unsubscribeEvent(uint id, QObject * obj) = 0;

    /**
     * Sends the event to all the subscribers
     * @param event The event object
     *
     * This function sends the event to all the subscribers. The event object is destroyed when the event loop
     * is finished for this event.
     *
     * The event object shall be allocated in the heap.
     */
    virtual void broadcastEvent(Event * event) = 0;

};

} // namespace eVaf::Common
} // namespace eVaf

#endif // ieventqueue.h