summaryrefslogtreecommitdiffstats
path: root/dom/interfaces/push
diff options
context:
space:
mode:
Diffstat (limited to 'dom/interfaces/push')
-rw-r--r--dom/interfaces/push/moz.build13
-rw-r--r--dom/interfaces/push/nsIPushErrorReporter.idl45
-rw-r--r--dom/interfaces/push/nsIPushNotifier.idl94
-rw-r--r--dom/interfaces/push/nsIPushService.idl150
4 files changed, 302 insertions, 0 deletions
diff --git a/dom/interfaces/push/moz.build b/dom/interfaces/push/moz.build
new file mode 100644
index 000000000..5c59f3941
--- /dev/null
+++ b/dom/interfaces/push/moz.build
@@ -0,0 +1,13 @@
+# -*- Mode: python; indent-tabs-mode: nil; tab-width: 40 -*-
+# vim: set filetype=python:
+# 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/.
+
+XPIDL_SOURCES += [
+ 'nsIPushErrorReporter.idl',
+ 'nsIPushNotifier.idl',
+ 'nsIPushService.idl',
+]
+
+XPIDL_MODULE = 'dom_push'
diff --git a/dom/interfaces/push/nsIPushErrorReporter.idl b/dom/interfaces/push/nsIPushErrorReporter.idl
new file mode 100644
index 000000000..d9cef82ea
--- /dev/null
+++ b/dom/interfaces/push/nsIPushErrorReporter.idl
@@ -0,0 +1,45 @@
+/* -*- 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"
+
+[scriptable, uuid(b58249f9-1a04-48cc-bc20-2c992d64c73e)]
+interface nsIPushErrorReporter : nsISupports
+{
+ /**
+ * Ack types, reported when the Push service acknowledges an incoming message.
+ *
+ * Acks are sent before the message is dispatched to the service worker,
+ * since the server delays new messages until all outstanding ones have been
+ * acked. |reportDeliveryError| will be called if an error occurs in the
+ * worker's `push` event handler after acking the message.
+ */
+ const uint16_t ACK_DELIVERED = 0;
+ const uint16_t ACK_DECRYPTION_ERROR = 1;
+ const uint16_t ACK_NOT_DELIVERED = 2;
+
+ /**
+ * Unsubscribe reasons, reported when the service drops a subscription.
+ */
+ const uint16_t UNSUBSCRIBE_MANUAL = 3;
+ const uint16_t UNSUBSCRIBE_QUOTA_EXCEEDED = 4;
+ const uint16_t UNSUBSCRIBE_PERMISSION_REVOKED = 5;
+
+ /**
+ * Delivery error reasons, reported when a service worker fails to handle
+ * an incoming push message in its `push` event handler.
+ */
+ const uint16_t DELIVERY_UNCAUGHT_EXCEPTION = 6;
+ const uint16_t DELIVERY_UNHANDLED_REJECTION = 7;
+ const uint16_t DELIVERY_INTERNAL_ERROR = 8;
+
+ /**
+ * Reports a `push` event handler error to the Push service. |messageId| is
+ * an opaque string passed to `nsIPushNotifier.notifyPush{WithData}`.
+ * |reason| is a delivery error reason.
+ */
+ void reportDeliveryError(in DOMString messageId,
+ [optional] in uint16_t reason);
+};
diff --git a/dom/interfaces/push/nsIPushNotifier.idl b/dom/interfaces/push/nsIPushNotifier.idl
new file mode 100644
index 000000000..b29e73056
--- /dev/null
+++ b/dom/interfaces/push/nsIPushNotifier.idl
@@ -0,0 +1,94 @@
+/* -*- 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"
+
+%{C++
+#define PUSHNOTIFIER_CONTRACTID \
+ "@mozilla.org/push/Notifier;1"
+
+// These constants are duplicated in `PushComponents.js`.
+#define OBSERVER_TOPIC_PUSH "push-message"
+#define OBSERVER_TOPIC_SUBSCRIPTION_CHANGE "push-subscription-change"
+#define OBSERVER_TOPIC_SUBSCRIPTION_MODIFIED "push-subscription-modified"
+%}
+
+interface nsIPrincipal;
+
+/**
+ * Fires XPCOM observer notifications and service worker events for
+ * messages sent to push subscriptions.
+ */
+[scriptable, builtinclass, uuid(b00dfdeb-14e5-425b-adc7-b531442e3216)]
+interface nsIPushNotifier : nsISupports
+{
+ /**
+ * Fires a `push-message` observer notification, and sends a `push` event to
+ * the service worker registered for the |scope|. |messageId| is an opaque ID
+ * used to report errors if the worker fails to handle the message.
+ */
+ void notifyPush(in ACString scope, in nsIPrincipal principal,
+ in DOMString messageId);
+
+ /**
+ * Same as `notifyPush`, except the subject of the observer notification
+ * receives an `nsIPushMessage` instance containing the |data|. Service
+ * workers can access the |data| via the `PushMessageData` WebIDL interface.
+ */
+ void notifyPushWithData(in ACString scope, in nsIPrincipal principal,
+ in DOMString messageId,
+ [optional] in uint32_t dataLen,
+ [array, size_is(dataLen)] in uint8_t data);
+
+ /**
+ * Fires a `push-subscription-change` observer notification, and sends a
+ * `pushsubscriptionchange` event to the service worker registered for the
+ * |scope|.
+ */
+ void notifySubscriptionChange(in ACString scope, in nsIPrincipal principal);
+
+ /**
+ * Fires a `push-subscription-modified` observer notification. Chrome code
+ * can listen for this notification to see when a subscription is added,
+ * updated, removed, or expired for any |scope|.
+ *
+ * This is useful for Dev Tools and debugging add-ons that passively observe
+ * when subscriptions are created or dropped. Other callers should listen for
+ * `push-subscription-change` and resubscribe instead.
+ */
+ void notifySubscriptionModified(in ACString scope, in nsIPrincipal principal);
+
+ void notifyError(in ACString scope, in nsIPrincipal principal,
+ in DOMString message, in uint32_t flags);
+};
+
+/**
+ * Provides methods for retrieving push message data in different formats.
+ * This interface resembles the `PushMessageData` WebIDL interface.
+ */
+[scriptable, builtinclass, uuid(dfc4f151-cead-40df-8eb7-7a7a67c54b16)]
+interface nsIPushData : nsISupports
+{
+ /** Extracts the data as a UTF-8 text string. */
+ DOMString text();
+
+ /** Extracts the data as a JSON value. */
+ [implicit_jscontext] jsval json();
+
+ /** Extracts the raw binary data. */
+ void binary([optional] out uint32_t dataLen,
+ [array, retval, size_is(dataLen)] out uint8_t data);
+};
+
+/**
+ * The subject of a `push-message` observer notification. |data| may be |null|
+ * for messages without data.
+ */
+[scriptable, builtinclass, uuid(b9d063ca-0e3f-4fee-be4b-ea9103263433)]
+interface nsIPushMessage : nsISupports
+{
+ readonly attribute nsIPrincipal principal;
+ readonly attribute nsIPushData data;
+};
diff --git a/dom/interfaces/push/nsIPushService.idl b/dom/interfaces/push/nsIPushService.idl
new file mode 100644
index 000000000..920169d35
--- /dev/null
+++ b/dom/interfaces/push/nsIPushService.idl
@@ -0,0 +1,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);
+};