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_INVALIDATION_SERVICE_H_ 6 #define COMPONENTS_INVALIDATION_INVALIDATION_SERVICE_H_ 7 8 #include "base/callback_forward.h" 9 #include "components/invalidation/invalidation_util.h" 10 #include "components/invalidation/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: ~InvalidationService()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. 80 // 81 // Registered IDs are persisted across restarts of sync. 82 virtual void UpdateRegisteredInvalidationIds( 83 syncer::InvalidationHandler* handler, 84 const syncer::ObjectIdSet& ids) = 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_INVALIDATION_SERVICE_H_ 117