summaryrefslogtreecommitdiffstats
path: root/dom/interfaces/push/nsIPushService.idl
blob: 920169d3546b60b6970f4452cc609985b6c4b2d1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
/* -*- 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"

interface nsIPrincipal;

/**
 * A push subscription, passed as an argument to a subscription callback.
 * Similar to the `PushSubscription` WebIDL interface.
 */
[scriptable, uuid(1de32d5c-ea88-4c9e-9626-b032bd87f415)]
interface nsIPushSubscription : nsISupports
{
  readonly attribute DOMString endpoint;
  readonly attribute long long pushCount;
  readonly attribute long long lastPush;
  readonly attribute long quota;
  readonly attribute bool isSystemSubscription;
  readonly attribute jsval p256dhPrivateKey;

  bool quotaApplies();
  bool isExpired();

  void getKey(in DOMString name,
              [optional] out uint32_t keyLen,
              [array, size_is(keyLen), retval] out uint8_t key);
};

/**
 * Called by methods that return a push subscription. A non-success
 * |status| indicates that there was a problem returning the
 * subscription, and the |subscription| argument should be ignored. Otherwise,
 * |subscription| will point to a valid push subscription, or |null| if the
 * subscription does not exist.
 */
 [scriptable, uuid(1799c074-9d52-46b0-ab3c-c09790732f6f), function]
 interface nsIPushSubscriptionCallback : nsISupports
 {
   void onPushSubscription(in nsresult status,
                           in nsIPushSubscription subscription);
 };

/**
 * Called by |unsubscribe|. A non-success |status| indicates that there was
 * a problem unsubscribing, and the |success| argument should be ignored.
 * Otherwise, |success| is true if unsubscribing was successful, and false if
 * the subscription does not exist.
 */
[scriptable, uuid(d574118f-61a9-4270-b1f6-4461aa85c4f5), function]
interface nsIUnsubscribeResultCallback : nsISupports
{
  void onUnsubscribe(in nsresult status, in bool success);
};

/**
 * Called by |clearForDomain|. A non-success |status| indicates that there was
 * a problem clearing subscriptions for the given domain.
 */
[scriptable, uuid(bd47b38e-8bfa-4f92-834e-832a4431e05e), function]
interface nsIPushClearResultCallback : nsISupports
{
  void onClear(in nsresult status);
};

/**
 * A service for components to subscribe and receive push messages from web
 * services. This functionality is exposed to content via the Push DOM API,
 * which uses service workers. This interface exists to support the DOM API,
 * and allows privileged code to receive messages without migrating to service
 * workers.
 */
[scriptable, uuid(678ef584-bf25-47aa-ac84-03efc0865b68)]
interface nsIPushService : nsISupports
{
  /** Observer topic names, exported for convenience. */
  readonly attribute DOMString pushTopic;
  readonly attribute DOMString subscriptionChangeTopic;
  readonly attribute DOMString subscriptionModifiedTopic;

  /**
   * Creates a push subscription for the given |scope| URL and |principal|.
   * If a subscription already exists for this |(scope, principal)| pair,
   * the callback will receive the existing record as the second argument.
   *
   * The |endpoint| property of the subscription record is a URL string
   * that can be used to send push messages to subscribers.
   *
   * Each incoming message fires a `push-message` observer notification, with
   * an `nsIPushMessage` 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 |principal| and the data set to
   * |scope|. Servers may drop subscriptions at any time, so callers should
   * recreate subscriptions if desired.
   */
  void subscribe(in DOMString scope, in nsIPrincipal principal,
                 in nsIPushSubscriptionCallback callback);

  /**
   * Creates a restricted push subscription with the given public |key|. The
   * application server must use the corresponding private key to authenticate
   * message delivery requests, as described in draft-thomson-webpush-vapid.
   */
  void subscribeWithKey(in DOMString scope, in nsIPrincipal principal,
                        in uint32_t keyLength,
                        [const, array, size_is(keyLength)] in uint8_t key,
                        in nsIPushSubscriptionCallback callback);

  /**
   * Removes a push subscription for the given |scope|.
   */
  void unsubscribe(in DOMString scope, in nsIPrincipal principal,
                   in nsIUnsubscribeResultCallback callback);

  /**
   * Retrieves the subscription record associated with the given
   * |(scope, principal)| pair. If the subscription does not exist, the
   * callback will receive |null| as the second argument.
   */
  void getSubscription(in DOMString scope, in nsIPrincipal principal,
                       in nsIPushSubscriptionCallback callback);

  /**
   * Drops every subscription for the given |domain|, or all domains if
   * |domain| is "*".
   */
  void clearForDomain(in DOMString domain,
                      in nsIPushClearResultCallback callback);
};

[scriptable, uuid(a2555e70-46f8-4b52-bf02-d978b979d143)]
interface nsIPushQuotaManager : nsISupports
{
  /**
   * Informs the quota manager that a notification
   * for the given origin has been shown. Used to
   * determine if push quota should be relaxed.
   */
  void notificationForOriginShown(in string origin);

  /**
   * Informs the quota manager that a notification
   * for the given origin has been closed. Used to
   * determine if push quota should be relaxed.
   */
  void notificationForOriginClosed(in string origin);
};