components/invalidation/invalidator.h

   1 // Copyright 2014 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 // Interface to the invalidator, which is an object that receives
   6 // invalidations for registered object IDs. The corresponding
   7 // InvalidationHandler is notifier when such an event occurs.
   8
   9 #ifndef COMPONENTS_INVALIDATION_INVALIDATOR_H_
  10 #define COMPONENTS_INVALIDATION_INVALIDATOR_H_
  11
  12 #include <string>
  13
  14 #include "base/callback.h"
  15 #include "components/invalidation/invalidation_export.h"
  16 #include "components/invalidation/invalidation_util.h"
  17 #include "components/invalidation/invalidator_state.h"
  18
  19 namespace syncer {
  20 class InvalidationHandler;
  21
  22 class INVALIDATION_EXPORT Invalidator {
  23  public:
  24   Invalidator();
  25   virtual ~Invalidator();
  26
  27   // Clients should follow the pattern below:
  28   //
  29   // When starting the client:
  30   //
  31   //   invalidator->RegisterHandler(client_handler);
  32   //
  33   // When the set of IDs to register changes for the client during its lifetime
  34   // (i.e., between calls to RegisterHandler(client_handler) and
  35   // UnregisterHandler(client_handler):
  36   //
  37   //   invalidator->UpdateRegisteredIds(client_handler, client_ids);
  38   //
  39   // When shutting down the client for profile shutdown:
  40   //
  41   //   invalidator->UnregisterHandler(client_handler);
  42   //
  43   // Note that there's no call to UpdateRegisteredIds() -- this is because the
  44   // invalidation API persists registrations across browser restarts.
  45   //
  46   // When permanently shutting down the client, e.g. when disabling the related
  47   // feature:
  48   //
  49   //   invalidator->UpdateRegisteredIds(client_handler, ObjectIdSet());
  50   //   invalidator->UnregisterHandler(client_handler);
  51   //
  52   // It is an error to have registered handlers when an invalidator is
  53   // destroyed; clients must ensure that they unregister themselves
  54   // before then.
  55
  56   // Starts sending notifications to |handler|.  |handler| must not be NULL,
  57   // and it must not already be registered.
  58   virtual void RegisterHandler(InvalidationHandler* handler) = 0;
  59
  60   // Updates the set of ObjectIds associated with |handler|.  |handler| must
  61   // not be NULL, and must already be registered.  An ID must be registered for
  62   // at most one handler.
  63   virtual void UpdateRegisteredIds(InvalidationHandler* handler,
  64                                    const ObjectIdSet& ids) = 0;
  65
  66   // Stops sending notifications to |handler|.  |handler| must not be NULL, and
  67   // it must already be registered.  Note that this doesn't unregister the IDs
  68   // associated with |handler|.
  69   virtual void UnregisterHandler(InvalidationHandler* handler) = 0;
  70
  71   // Returns the current invalidator state.  When called from within
  72   // InvalidationHandler::OnInvalidatorStateChange(), this must return
  73   // the updated state.
  74   virtual InvalidatorState GetInvalidatorState() const = 0;
  75
  76   // The observers won't be notified of any notifications until
  77   // UpdateCredentials is called at least once. It can be called more than
  78   // once.
  79   virtual void UpdateCredentials(
  80       const std::string& email, const std::string& token) = 0;
  81
  82   // Requests internal detailed status to be posted back to the callback.
  83   virtual void RequestDetailedStatus(
  84       base::Callback<void(const base::DictionaryValue&)> callback) const = 0;
  85 };
  86 }  // namespace syncer
  87
  88 #endif  // COMPONENTS_INVALIDATION_INVALIDATOR_H_