nsIPushService.idl (5845B)
1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2 /* This Source Code Form is subject to the terms of the Mozilla Public 3 * License, v. 2.0. If a copy of the MPL was not distributed with this 4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 5 6 #include "nsISupports.idl" 7 8 interface nsIPrincipal; 9 10 /** 11 * A push subscription, passed as an argument to a subscription callback. 12 * Similar to the `PushSubscription` WebIDL interface. 13 */ 14 [scriptable, uuid(1de32d5c-ea88-4c9e-9626-b032bd87f415)] 15 interface nsIPushSubscription : nsISupports 16 { 17 readonly attribute AString endpoint; 18 readonly attribute long long pushCount; 19 readonly attribute long long lastPush; 20 readonly attribute long quota; 21 readonly attribute boolean isSystemSubscription; 22 readonly attribute jsval p256dhPrivateKey; 23 24 boolean quotaApplies(); 25 boolean isExpired(); 26 27 Array<uint8_t> getKey(in AString name); 28 }; 29 30 /** 31 * Called by methods that return a push subscription. A non-success 32 * |status| indicates that there was a problem returning the 33 * subscription, and the |subscription| argument should be ignored. Otherwise, 34 * |subscription| will point to a valid push subscription, or |null| if the 35 * subscription does not exist. 36 */ 37 [scriptable, uuid(1799c074-9d52-46b0-ab3c-c09790732f6f), function] 38 interface nsIPushSubscriptionCallback : nsISupports 39 { 40 void onPushSubscription(in nsresult status, 41 in nsIPushSubscription subscription); 42 }; 43 44 /** 45 * Called by |unsubscribe|. A non-success |status| indicates that there was 46 * a problem unsubscribing, and the |success| argument should be ignored. 47 * Otherwise, |success| is true if unsubscribing was successful, and false if 48 * the subscription does not exist. 49 */ 50 [scriptable, uuid(d574118f-61a9-4270-b1f6-4461aa85c4f5), function] 51 interface nsIUnsubscribeResultCallback : nsISupports 52 { 53 void onUnsubscribe(in nsresult status, in boolean success); 54 }; 55 56 /** 57 * Called by |clearForDomain|. A non-success |status| indicates that there was 58 * a problem clearing subscriptions for the given domain. 59 */ 60 [scriptable, uuid(bd47b38e-8bfa-4f92-834e-832a4431e05e), function] 61 interface nsIPushClearResultCallback : nsISupports 62 { 63 void onClear(in nsresult status); 64 }; 65 66 /** 67 * A service for components to subscribe and receive push messages from web 68 * services. This functionality is exposed to content via the Push DOM API, 69 * which uses service workers. This interface exists to support the DOM API, 70 * and allows privileged code to receive messages without migrating to service 71 * workers. 72 */ 73 [scriptable, uuid(678ef584-bf25-47aa-ac84-03efc0865b68)] 74 interface nsIPushService : nsISupports 75 { 76 /** Observer topic names, exported for convenience. */ 77 readonly attribute AString pushTopic; 78 readonly attribute AString subscriptionChangeTopic; 79 readonly attribute AString subscriptionModifiedTopic; 80 81 /** 82 * Creates a push subscription for the given |scope| URL and |principal|. 83 * If a subscription already exists for this |(scope, principal)| pair, 84 * the callback will receive the existing record as the second argument. 85 * 86 * The |endpoint| property of the subscription record is a URL string 87 * that can be used to send push messages to subscribers. 88 * 89 * Each incoming message fires a `push-message` observer notification, with 90 * an `nsIPushMessage` as the subject and the |scope| as the data. 91 * 92 * If the server drops a subscription, a `push-subscription-change` observer 93 * will be fired, with the subject set to |principal| and the data set to 94 * |scope|. Servers may drop subscriptions at any time, so callers should 95 * recreate subscriptions if desired. 96 */ 97 void subscribe(in AString scope, in nsIPrincipal principal, 98 in nsIPushSubscriptionCallback callback); 99 100 /** 101 * Creates a restricted push subscription with the given public |key|. The 102 * application server must use the corresponding private key to authenticate 103 * message delivery requests, as described in draft-thomson-webpush-vapid. 104 */ 105 void subscribeWithKey(in AString scope, in nsIPrincipal principal, 106 in Array<uint8_t> key, 107 in nsIPushSubscriptionCallback callback); 108 109 /** 110 * Removes a push subscription for the given |scope|. 111 */ 112 void unsubscribe(in AString scope, in nsIPrincipal principal, 113 in nsIUnsubscribeResultCallback callback); 114 115 /** 116 * Retrieves the subscription record associated with the given 117 * |(scope, principal)| pair. If the subscription does not exist, the 118 * callback will receive |null| as the second argument. 119 */ 120 void getSubscription(in AString scope, in nsIPrincipal principal, 121 in nsIPushSubscriptionCallback callback); 122 123 /** 124 * Drops every subscription for the given |domain|, or all domains if 125 * |domain| is "*". 126 * Optionally pass an OriginAttributesPattern to match against entries. 127 */ 128 void clearForDomain(in AString domain, 129 in jsval originAttributesPattern, 130 in nsIPushClearResultCallback callback); 131 132 /** 133 * Drops every subscription for the given |principal|. 134 */ 135 void clearForPrincipal(in nsIPrincipal principal, 136 in nsIPushClearResultCallback callback); 137 }; 138 139 [scriptable, uuid(a2555e70-46f8-4b52-bf02-d978b979d143)] 140 interface nsIPushQuotaManager : nsISupports 141 { 142 /** 143 * Informs the quota manager that a notification 144 * for the given origin has been shown. Used to 145 * determine if push quota should be relaxed. 146 */ 147 void notificationForOriginShown(in string origin); 148 149 /** 150 * Informs the quota manager that a notification 151 * for the given origin has been closed. Used to 152 * determine if push quota should be relaxed. 153 */ 154 void notificationForOriginClosed(in string origin); 155 };