michael@0: // Copyright (c) 2006-2008 The Chromium Authors. All rights reserved.
michael@0: // Use of this source code is governed by a BSD-style license that can be
michael@0: // found in the LICENSE file.
michael@0: 
michael@0: // This file describes a central switchboard for notifications that might
michael@0: // happen in various parts of the application, and allows users to register
michael@0: // observers for various classes of events that they're interested in.
michael@0: 
michael@0: #ifndef CHROME_COMMON_NOTIFICATION_SERVICE_H_
michael@0: #define CHROME_COMMON_NOTIFICATION_SERVICE_H_
michael@0: 
michael@0: #include <map>
michael@0: 
michael@0: #include "base/observer_list.h"
michael@0: #include "chrome/common/notification_details.h"
michael@0: #include "chrome/common/notification_observer.h"
michael@0: #include "chrome/common/notification_source.h"
michael@0: #include "chrome/common/notification_type.h"
michael@0: 
michael@0: class NotificationObserver;
michael@0: 
michael@0: class NotificationService {
michael@0:  public:
michael@0:   // Returns the NotificationService object for the current thread, or NULL if
michael@0:   // none.
michael@0:   static NotificationService* current();
michael@0: 
michael@0:   // Normally instantiated when the thread is created.  Not all threads have
michael@0:   // a NotificationService.  Only one instance should be created per thread.
michael@0:   NotificationService();
michael@0:   ~NotificationService();
michael@0: 
michael@0:   // Registers a NotificationObserver to be called whenever a matching
michael@0:   // notification is posted.  Observer is a pointer to an object subclassing
michael@0:   // NotificationObserver to be notified when an event matching the other two
michael@0:   // parameters is posted to this service.  Type is the type of events to
michael@0:   // be notified about (or NOTIFY_ALL to receive events of all types).
michael@0:   // Source is a NotificationSource object (created using
michael@0:   // "Source<classname>(pointer)"), if this observer only wants to
michael@0:   // receive events from that object, or NotificationService::AllSources()
michael@0:   // to receive events from all sources.
michael@0:   //
michael@0:   // A given observer can be registered only once for each combination of
michael@0:   // type and source.  If the same object is registered more than once,
michael@0:   // it must be removed for each of those combinations of type and source later.
michael@0:   //
michael@0:   // The caller retains ownership of the object pointed to by observer.
michael@0:   void AddObserver(NotificationObserver* observer,
michael@0:                    NotificationType type, const NotificationSource& source);
michael@0: 
michael@0:   // Removes the object pointed to by observer from receiving notifications
michael@0:   // that match type and source.  If no object matching the parameters is
michael@0:   // currently registered, this method is a no-op.
michael@0:   void RemoveObserver(NotificationObserver* observer,
michael@0:                       NotificationType type, const NotificationSource& source);
michael@0: 
michael@0:   // Synchronously posts a notification to all interested observers.
michael@0:   // Source is a reference to a NotificationSource object representing
michael@0:   // the object originating the notification (can be
michael@0:   // NotificationService::AllSources(), in which case
michael@0:   // only observers interested in all sources will be notified).
michael@0:   // Details is a reference to an object containing additional data about
michael@0:   // the notification.  If no additional data is needed, NoDetails() is used.
michael@0:   // There is no particular order in which the observers will be notified.
michael@0:   void Notify(NotificationType type,
michael@0:               const NotificationSource& source,
michael@0:               const NotificationDetails& details);
michael@0: 
michael@0:   // Returns a NotificationSource that represents all notification sources
michael@0:   // (for the purpose of registering an observer for events from all sources).
michael@0:   static Source<void> AllSources() { return Source<void>(NULL); }
michael@0: 
michael@0:   // Returns a NotificationDetails object that represents a lack of details
michael@0:   // associated with a notification.  (This is effectively a null pointer.)
michael@0:   static Details<void> NoDetails() { return Details<void>(NULL); }
michael@0: 
michael@0:  private:
michael@0:   typedef base::ObserverList<NotificationObserver> NotificationObserverList;
michael@0:   typedef std::map<uintptr_t, NotificationObserverList*> NotificationSourceMap;
michael@0: 
michael@0:   // Convenience function to determine whether a source has a
michael@0:   // NotificationObserverList in the given map;
michael@0:   static bool HasKey(const NotificationSourceMap& map,
michael@0:                      const NotificationSource& source);
michael@0: 
michael@0:   // Keeps track of the observers for each type of notification.
michael@0:   // Until we get a prohibitively large number of notification types,
michael@0:   // a simple array is probably the fastest way to dispatch.
michael@0:   NotificationSourceMap observers_[NotificationType::NOTIFICATION_TYPE_COUNT];
michael@0: 
michael@0: #ifndef NDEBUG
michael@0:   // Used to check to see that AddObserver and RemoveObserver calls are
michael@0:   // balanced.
michael@0:   int observer_counts_[NotificationType::NOTIFICATION_TYPE_COUNT];
michael@0: #endif
michael@0: 
michael@0:   DISALLOW_COPY_AND_ASSIGN(NotificationService);
michael@0: };
michael@0: 
michael@0: #endif  // CHROME_COMMON_NOTIFICATION_SERVICE_H_