/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

/**
 * A service for components to subscribe and receive push messages from web
 * services. This functionality is exposed to content via the Push API, which
 * uses service workers to notify applications. This interface exists to allow
 * privileged code to receive messages without migrating to service workers.
 */
[scriptable, uuid(abde228b-7d14-4cab-b1f9-9f87750ede0f)]
interface nsIPushNotificationService : nsISupports
{
  /**
   * Creates a push subscription for the given |scope| URL and |pageURL|.
   * Returns a promise for the new subscription record, or the existing
   * record if this |scope| already has a subscription.
   *
   * The |pushEndpoint| property of the subscription record is a URL string
   * that can be used to send push messages to subscribers. For details,
   * please see the Simple Push protocol docs.
   *
   * Each incoming message fires a `push-notification` observer
   * notification, with an `nsIPushObserverNotification` as the subject and
   * the |scope| as the data.
   *
   * If the server drops a subscription, a `push-subscription-change` observer
   * will be fired, with the subject set to `null` and the data set to |scope|.
   * Servers may drop subscriptions at any time, so callers should recreate
   * subscriptions if desired.
   */
  jsval register(in string scope, in jsval originAttributes);

  /**
   * Revokes a push subscription for the given |scope|. Returns a promise
   * for the revoked subscription record, or `null` if the |scope| is not
   * subscribed to receive notifications.
   */
  jsval unregister(in string scope, in jsval originAttributes);

  /**
   * Returns a promise for the subscription record associated with the
   * given |scope|, or `null` if the |scope| does not have a subscription.
   */
  jsval registration(in string scope, in jsval originAttributes);

  /**
   * Clear all subscriptions
   */
   jsval clearAll();
};