chromium/components/invalidation/public/invalidation_service.h

// Copyright 2014 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef COMPONENTS_INVALIDATION_PUBLIC_INVALIDATION_SERVICE_H_
#define COMPONENTS_INVALIDATION_PUBLIC_INVALIDATION_SERVICE_H_

#include "components/invalidation/public/invalidation_util.h"
#include "components/invalidation/public/invalidator_state.h"

namespace invalidation {

class InvalidationHandler;

// Interface for classes that handle invalidation subscriptions and send out
// invalidations to registered handlers.
//
// Invalidation handlers should follow the pattern below:
//
// When starting the handler:
//
//   service->AddObserver(client_handler);
//
// When the set of topics to register changes for the handler during its
// lifetime (i.e., between calls to AddObserver(client_handler)
// and RemoveObserver(client_handler):
//
//   service->UpdateInterestedTopics(client_handler, client_topics);
//
// When shutting down the handler for browser shutdown:
//
//   service->RemoveObserver(client_handler);
//
// Note that there's no need to call to unregister topics. The
// invalidation API persists subscribed topics across browser restarts.
//
// If an invalidation handler cares about the invalidator state, it should also
// do the following when starting the handler:
//
//   invalidator_state = service->GetInvalidatorState();
//
// It can also do the above in OnInvalidatorStateChange(), or it can use the
// argument to OnInvalidatorStateChange().
//
// It is an error to have registered handlers when an
// InvalidationService is shut down; clients must ensure that they
// unregister themselves before then. (Depending on the
// InvalidationService, shutdown may be equivalent to destruction, or
// a separate function call like Shutdown()).
class InvalidationService { … };

}  // namespace invalidation

#endif  // COMPONENTS_INVALIDATION_PUBLIC_INVALIDATION_SERVICE_H_