jaus++/2.0/include/jaus/core/events/events.h

Go to the documentation of this file.

#ifndef __JAUS_CORE_EVENTS_EVENTS__H
#define __JAUS_CORE_EVENTS_EVENTS__H

#include "jaus/core/service.h"
#include "jaus/core/transport/transport.h"
#include <cxutils/timer.h>
#include <map>

namespace JAUS
{
    class JAUS_CORE_DLL Events : public Service
    {
    public:
        const static std::string Name; 
        // Type of Events
        enum Type
        {
            Periodic = 0,
            EveryChange
        };
        class JAUS_CORE_DLL Subscription
        {
            friend class Events;
        public:
            typedef std::map<UInt, Subscription> Map;
            typedef std::vector<Subscription> List;
            Subscription();
            Subscription(const Subscription& data);
            ~Subscription();
            Subscription& operator=(const Subscription& data);
            Byte mID;                   
            Byte mSequenceNumber;       
            double mPeriodicRate;       
            Message* mpQueryMessage;    
            Events::Type mType;         
            Time::Stamp mUpdateTimeMs;  
            Address mProducer;          
            Address::Set mClients;      
        private:
            double mTriggerTimeSeconds; 
            Service* mpEventService;    
        };
        class JAUS_CORE_DLL Child : public Service
        {
        public:
            Child(const ID& serviceIdentifier, const ID& parentServiceIdentifier);
            ~Child();
            // Signals the data has changed (i.e. an event has occured).
            void SignalEvent(const UShort reportMessageCode);
            // Signals the event subscription needs to be updated.
            void SignalEvent(const Subscription& info);
            // Method called when an Event has been signaled, generates an Event message.
            virtual bool GenerateEvent(const Events::Subscription& info) const = 0;
            // Method called to determine if an Event is supported by the service.
            virtual bool IsEventSupported(const Events::Type type,
                                          const double requestedPeriodicRate,
                                          const Message* queryMessage,
                                          double& confirmedPeriodicRate,
                                          std::string& errorMessage) const = 0;
            // Method for generating an event.
            void SendEvent(const Events::Subscription& info,
                           const Message* payload) const;
            // Gets a pointer to the events service.
            Events* EventsService();
            // Gets a pointer to the events service.
            const Events* EventsService() const;
        };
        class JAUS_CORE_DLL Callback : public Transport::Callback
        {
        public:
            Callback() {}
            virtual ~Callback() {}
            virtual void ProcessEvent(const Events::Type type,
                                      const Byte eventID,
                                      const Byte sequenceNumber,
                                      const Message* message) {}
        };
        Events();
        ~Events();
        // Method called on Shutdown.
        virtual void Shutdown();
        // Request an Every Change Event from a service provider.
        bool RequestEveryChangeEvent(const Address& provider,                     // Whom to get the subscription from.
                                     const Message* query,                        // Query message that maps to desired Report.
                                     const unsigned int waitTimeMs = Service::DefaultWaitMs);
        // Request a Periodic Event from a service provider.
        bool RequestPeriodicEvent(const Address& provider,                        // Whom to get the subscription from.
                                  const Message* query,                           // Query message that maps to desired Report.
                                  const double desiredPeriodicRate = 1.0,         // Update rate desired.
                                  const double minimumPeriodicRate = 0.9,         // Minimum rate acceptable (slightly less for rounding error).
                                  const unsigned int waitTimeMs = DefaultWaitMs); // How long to wait for confirmation. 
        // Signals the Events service that the type of data has changed.
        void SignalEvent(const UShort reportMessageCode, const bool changeOnly = true);
        // Signals the Events service that the type of data has changed.
        void SignalEvent(const Subscription& info, const bool changeOnly = true);
        // Method used to cancel a subscriptoin.
        bool CancelSubscription(const Address& id,
                                const UShort reportMessageCode,
                                const unsigned int waitTimeMs = Service::DefaultWaitMs);
        // Method used to cancel a subscriptoin.
        bool CancelSubscription(const Address& id,
                                const UShort reportMessageCode,
                                Byte eventID,
                                const unsigned int waitTimeMs);
        // Method used to check if a subscription exists.
        bool HaveSubscription(const UShort reportMessageCode, 
                              const Address& id,
                              const bool verifyWithQuery = false,
                              const unsigned int waitTimeMs = Service::DefaultWaitMs) const;
        // Method to check if there are subscribers to specific events.
        bool HaveSubscribers(const UShort reportMessageCode) const;
        // Events service is always discoverable.
        virtual bool IsDiscoverable() const { return true; }
        // Processes messages associated with the Events service.
        virtual void Receive(const Message* message);  
        // Creates messages associated with the events service.
        virtual Message* CreateMessage(const UShort messageCode) const;
        // When called verifies that no subscriptions have been lost.
        virtual void CheckServiceStatus(const unsigned int timeSinceLastCheckMs);
        // Sets how long to wait before the Service verifies event subscriptions are valid.
        void SetEventSubscriptionCheckThreshold(const Time::Stamp timeMs = 5000) { mCheckEventsTimeMs = timeMs; }
        // Gets a copy of the subscriptions from a source, filtering by type.
        Subscription::List GetSubscriptions(const Address& source = Address(),
                                            const UShort reportType = 0) const;
        // Gets all subscriptions of a type.
        Subscription::List GetSubscriptions(const UShort reportType) const;
        // Gets all events being produced of type.
        Subscription::List GetProducedEvents(const UShort reportType) const;
        // Method to register a callback for notifications of events received.
        void RegisterCallback(Events::Callback* callback);
        // Prints status about the service.
        virtual void PrintStatus() const;
    private:
        bool CancelSubscription(Subscription& sub, const unsigned int waitTimeMs);
        static void PeriodicEvent(void* args);
        CxUtils::Timer mPeriodicTimer;      
        Mutex mEventsMutex;                 
        Subscription::Map  mEvents;         
        Subscription::List mSubscriptions;  
        std::set<Byte> mRequestSet;         
        Mutex mRequestMutex;                
        Time::Stamp mCheckEventDelayMs;     
        Time::Stamp mCheckEventsTimeMs;     
        volatile bool mShutdownFlag;        
        Mutex mEventCallbackMutex;          
        Callback::Set mEventCallbacks;      
    };
}

#endif
/*  End of File */