content/common/notification_service.h

   1 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // This file describes a central switchboard for notifications that might
   6 // happen in various parts of the application, and allows users to register
   7 // observers for various classes of events that they're interested in.
   8
   9 #ifndef CONTENT_COMMON_NOTIFICATION_SERVICE_H_
  10 #define CONTENT_COMMON_NOTIFICATION_SERVICE_H_
  11 #pragma once
  12
  13 #include <map>
  14
  15 #include "base/observer_list.h"
  16 #include "content/common/content_notification_types.h"
  17 #include "content/common/notification_details.h"
  18 #include "content/common/notification_source.h"
  19
  20 class NotificationObserver;
  21
  22 class NotificationService {
  23  public:
  24   // Returns the NotificationService object for the current thread, or NULL if
  25   // none.
  26   static NotificationService* current();
  27
  28   // Normally instantiated when the thread is created.  Not all threads have
  29   // a NotificationService.  Only one instance should be created per thread.
  30   NotificationService();
  31   ~NotificationService();
  32
  33   // Synchronously posts a notification to all interested observers.
  34   // Source is a reference to a NotificationSource object representing
  35   // the object originating the notification (can be
  36   // NotificationService::AllSources(), in which case
  37   // only observers interested in all sources will be notified).
  38   // Details is a reference to an object containing additional data about
  39   // the notification.  If no additional data is needed, NoDetails() is used.
  40   // There is no particular order in which the observers will be notified.
  41   void Notify(int type,
  42               const NotificationSource& source,
  43               const NotificationDetails& details);
  44
  45   // Returns a NotificationSource that represents all notification sources
  46   // (for the purpose of registering an observer for events from all sources).
  47   static Source<void> AllSources() { return Source<void>(NULL); }
  48
  49   // Returns a NotificationDetails object that represents a lack of details
  50   // associated with a notification.  (This is effectively a null pointer.)
  51   static Details<void> NoDetails() { return Details<void>(NULL); }
  52
  53  private:
  54   friend class NotificationRegistrar;
  55
  56   typedef ObserverList<NotificationObserver> NotificationObserverList;
  57   typedef std::map<uintptr_t, NotificationObserverList*> NotificationSourceMap;
  58   typedef std::map<int, NotificationSourceMap> NotificationObserverMap;
  59   typedef std::map<int, int> NotificationObserverCount;
  60
  61   // Convenience function to determine whether a source has a
  62   // NotificationObserverList in the given map;
  63   static bool HasKey(const NotificationSourceMap& map,
  64                      const NotificationSource& source);
  65
  66   // NOTE: Rather than using this directly, you should use a
  67   // NotificationRegistrar.
  68   //
  69   // Registers a NotificationObserver to be called whenever a matching
  70   // notification is posted.  Observer is a pointer to an object subclassing
  71   // NotificationObserver to be notified when an event matching the other two
  72   // parameters is posted to this service.  Type is the type of events to be
  73   // notified about (or content::NOTIFICATION_ALL to receive events of all
  74   // types).
  75   // Source is a NotificationSource object (created using
  76   // "Source<classname>(pointer)"), if this observer only wants to
  77   // receive events from that object, or NotificationService::AllSources()
  78   // to receive events from all sources.
  79   //
  80   // A given observer can be registered only once for each combination of
  81   // type and source.  If the same object is registered more than once,
  82   // it must be removed for each of those combinations of type and source later.
  83   //
  84   // The caller retains ownership of the object pointed to by observer.
  85   void AddObserver(NotificationObserver* observer,
  86                    int type, const NotificationSource& source);
  87
  88   // NOTE: Rather than using this directly, you should use a
  89   // NotificationRegistrar.
  90   //
  91   // Removes the object pointed to by observer from receiving notifications
  92   // that match type and source.  If no object matching the parameters is
  93   // currently registered, this method is a no-op.
  94   void RemoveObserver(NotificationObserver* observer,
  95                       int type, const NotificationSource& source);
  96
  97   // Keeps track of the observers for each type of notification.
  98   // Until we get a prohibitively large number of notification types,
  99   // a simple array is probably the fastest way to dispatch.
 100   NotificationObserverMap observers_;
 101
 102 #ifndef NDEBUG
 103   // Used to check to see that AddObserver and RemoveObserver calls are
 104   // balanced.
 105   NotificationObserverCount observer_counts_;
 106 #endif
 107
 108   DISALLOW_COPY_AND_ASSIGN(NotificationService);
 109 };
 110
 111 #endif  // CONTENT_COMMON_NOTIFICATION_SERVICE_H_