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