diff options
Diffstat (limited to 'dom/interfaces/push')
| -rw-r--r-- | dom/interfaces/push/moz.build | 13 | ||||
| -rw-r--r-- | dom/interfaces/push/nsIPushErrorReporter.idl | 45 | ||||
| -rw-r--r-- | dom/interfaces/push/nsIPushNotifier.idl | 94 | ||||
| -rw-r--r-- | dom/interfaces/push/nsIPushService.idl | 150 |
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); +}; |