components/invalidation/public/invalidation_service.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 #ifndef COMPONENTS_INVALIDATION_PUBLIC_INVALIDATION_SERVICE_H_
   6 #define COMPONENTS_INVALIDATION_PUBLIC_INVALIDATION_SERVICE_H_
   7
   8 #include "base/callback_forward.h"
   9 #include "components/invalidation/public/invalidation_util.h"
  10 #include "components/invalidation/public/invalidator_state.h"
  11
  12 class IdentityProvider;
  13
  14 namespace syncer {
  15 class InvalidationHandler;
  16 }  // namespace syncer
  17
  18 namespace invalidation {
  19 class InvalidationLogger;
  20
  21 // Interface for classes that handle invalidation registrations and send out
  22 // invalidations to register handlers.
  23 //
  24 // Invalidation clients should follow the pattern below:
  25 //
  26 // When starting the client:
  27 //
  28 //   frontend->RegisterInvalidationHandler(client_handler);
  29 //
  30 // When the set of IDs to register changes for the client during its lifetime
  31 // (i.e., between calls to RegisterInvalidationHandler(client_handler) and
  32 // UnregisterInvalidationHandler(client_handler):
  33 //
  34 //   frontend->UpdateRegisteredInvalidationIds(client_handler, client_ids);
  35 //
  36 // When shutting down the client for browser shutdown:
  37 //
  38 //   frontend->UnregisterInvalidationHandler(client_handler);
  39 //
  40 // Note that there's no call to UpdateRegisteredIds() -- this is because the
  41 // invalidation API persists registrations across browser restarts.
  42 //
  43 // When permanently shutting down the client, e.g. when disabling the related
  44 // feature:
  45 //
  46 //   frontend->UpdateRegisteredInvalidationIds(client_handler, ObjectIdSet());
  47 //   frontend->UnregisterInvalidationHandler(client_handler);
  48 //
  49 // If an invalidation handler cares about the invalidator state, it should also
  50 // do the following when starting the client:
  51 //
  52 //   invalidator_state = frontend->GetInvalidatorState();
  53 //
  54 // It can also do the above in OnInvalidatorStateChange(), or it can use the
  55 // argument to OnInvalidatorStateChange().
  56 //
  57 // It is an error to have registered handlers when an
  58 // InvalidationFrontend is shut down; clients must ensure that they
  59 // unregister themselves before then. (Depending on the
  60 // InvalidationFrontend, shutdown may be equivalent to destruction, or
  61 // a separate function call like Shutdown()).
  62 //
  63 // NOTE(akalin): Invalidations that come in during browser shutdown may get
  64 // dropped.  This won't matter once we have an Acknowledge API, though: see
  65 // http://crbug.com/78462 and http://crbug.com/124149.
  66 class InvalidationService {
  67  public:
  68   virtual ~InvalidationService() {}
  69
  70   // Starts sending notifications to |handler|.  |handler| must not be NULL,
  71   // and it must not already be registered.
  72   //
  73   // Handler registrations are persisted across restarts of sync.
  74   virtual void RegisterInvalidationHandler(
  75       syncer::InvalidationHandler* handler) = 0;
  76
  77   // Updates the set of ObjectIds associated with |handler|.  |handler| must
  78   // not be NULL, and must already be registered.  An ID must be registered for
  79   // at most one handler.  If ID is already registered function returns false.
  80   //
  81   // Registered IDs are persisted across restarts of sync.
  82   virtual bool UpdateRegisteredInvalidationIds(
  83       syncer::InvalidationHandler* handler,
  84       const syncer::ObjectIdSet& ids) WARN_UNUSED_RESULT = 0;
  85
  86   // Stops sending notifications to |handler|.  |handler| must not be NULL, and
  87   // it must already be registered.  Note that this doesn't unregister the IDs
  88   // associated with |handler|.
  89   //
  90   // Handler registrations are persisted across restarts of sync.
  91   virtual void UnregisterInvalidationHandler(
  92       syncer::InvalidationHandler* handler) = 0;
  93
  94   // Returns the current invalidator state.  When called from within
  95   // InvalidationHandler::OnInvalidatorStateChange(), this must return
  96   // the updated state.
  97   virtual syncer::InvalidatorState GetInvalidatorState() const = 0;
  98
  99   // Returns the ID belonging to this invalidation client.  Can be used to
 100   // prevent the receipt of notifications of our own changes.
 101   virtual std::string GetInvalidatorClientId() const = 0;
 102
 103   // Return the logger used to debug invalidations
 104   virtual InvalidationLogger* GetInvalidationLogger() = 0;
 105
 106   // Triggers requests of internal status.
 107   virtual void RequestDetailedStatus(
 108       base::Callback<void(const base::DictionaryValue&)> post_caller) const = 0;
 109
 110   // Returns the identity provider.
 111   virtual IdentityProvider* GetIdentityProvider() = 0;
 112 };
 113
 114 }  // namespace invalidation
 115
 116 #endif  // COMPONENTS_INVALIDATION_PUBLIC_INVALIDATION_SERVICE_H_