chrome/common/extensions/api/notification_provider.idl

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // Use the <code>chrome.notificationProvider</code> API to intercept
   6 // notifications that would otherwise go into the Chrome Notification Center,
   7 // get notifiers' information, and inform notifiers about users' actions on the
   8 // notifications.
   9 namespace notificationProvider {
  10
  11   // TODO(liyanhou): Use notifications.PermissionLevel everywhere and delete
  12   // this type. See http://crbug.com/398266.
  13
  14   // whether notifications from this notifier is permitted or blocked.
  15   enum NotifierPermissionLevel {
  16     // User has elected to show notifications from the notifier.
  17     // This is the default at install time.
  18     granted,
  19
  20     // User has elected not to show notifications from the notifier.
  21     denied
  22   };
  23
  24   enum NotifierType {
  25     // Notifiers that are extensions or applications.
  26     application,
  27
  28     // Notifiers that are webistes.
  29     web
  30   };
  31
  32   dictionary Notifier {
  33     // Id of the notifier.
  34     DOMString notifierId;
  35
  36     // Type of the notifier.
  37     NotifierType type;
  38
  39     // Name of the notifier.
  40     DOMString name;
  41
  42     // Icon of the notifier.
  43     notifications.NotificationBitmap notifierIcon;
  44
  45     // Permission level of the notifier.
  46     NotifierPermissionLevel permissionLevel;
  47
  48     // If a notifier has advanced settings.
  49     boolean hasSettings;
  50   };
  51
  52   callback NotifyOnClearedCallback = void (boolean wasCleared);
  53
  54   callback NotifyOnClickedCallback = void (boolean matchExists);
  55
  56   callback NotifyOnButtonClickedCallback = void (boolean matchExists);
  57
  58   callback NotifyOnPermissionLevelChangedCallback = void (boolean wasChanged);
  59
  60   callback NotifyOnShowSettingsCallback = void (boolean hasSettings);
  61
  62   callback GetNotifierCallback = void (Notifier notifier);
  63
  64   callback GetAllNotifiersCallback = void (Notifier[] notifiers);
  65
  66   interface Functions {
  67     // Inform the notifier that the user cleared a notification sent from that
  68     // notifier.
  69     // |notifierId|: The id of the notifier that sent the notification.
  70     // |notificationId|: The id of the notification that was closed.
  71     // |callback|: Called to indicate whether a matching notification existed.
  72     static void notifyOnCleared(DOMString notifierId,
  73                                 DOMString notificationId,
  74                                 NotifyOnClearedCallback callback);
  75
  76     // Inform the notifier that the user clicked in a non-button area of a
  77     // notification sent from that notifier.
  78     // |notifierId|: The id of the notifier that sent the notification.
  79     // |notificationId|: The id of the notification that was clicked on.
  80     // |callback|: Called to indicate whether a matching notification existed.
  81     static void notifyOnClicked(DOMString notifierId,
  82                                 DOMString notificationId,
  83                                 NotifyOnClickedCallback callback);
  84
  85     // Inform the notifier that the user pressed a button in the notification
  86     // sent from that notifier.
  87     // |notifierId|: The id of the notifier that sent the notification.
  88     // |notificationId|: The id of the notification that was clicked on its
  89     // button.
  90     // |buttonIndex|: The index of the button that was clicked.
  91     // |callback|: Called to indicate whether a matching notification existed.
  92     static void notifyOnButtonClicked(DOMString notifierId,
  93                                       DOMString notificationId,
  94                                       long buttonIndex,
  95                                       NotifyOnButtonClickedCallback callback);
  96
  97     // Inform the notifier that the user changed the permission level of that
  98     // notifier.
  99     // |notifierId|: The id of the notifier that sent the notification.
 100     // |notifierType|: The type of the notifier that sent the notification.
 101     // |level|: The perission level of the notifier
 102     // |callback|: Called to indicate whether the permission level was changed.
 103     static void notifyOnPermissionLevelChanged(
 104                               DOMString notifierId,
 105                               NotifierType notifierType,
 106                               NotifierPermissionLevel level,
 107                               NotifyOnPermissionLevelChangedCallback callback);
 108
 109     // Inform the notifier that the user chose to see advanced settings of that
 110     // notifier.
 111     // |notifierId|: The id of the notifier that sent the notification.
 112     // |notifierType|: The type of the notifier that sent the notification.
 113     // |callback|: Called to indicate whether the notifier has extra settings.
 114     static void notifyOnShowSettings(DOMString notifierId,
 115                                      NotifierType notifierType,
 116                                      NotifyOnShowSettingsCallback callback);
 117
 118     // To get a notifier from it's notifier ID.
 119     // |callback|: Returns the notifier object of the given ID.
 120     static void getNotifier(GetNotifierCallback callback);
 121
 122     // To get all the notifiers that could send notifications.
 123     // |callback|: Returns the set of notifiers currently in the system.
 124     static void getAllNotifiers(GetAllNotifiersCallback callback);
 125   };
 126
 127   interface Events {
 128     // A new notification is created.
 129     // |notifierId|: The id of the notifier that sent the new notification.
 130     // |notificationId|: The id of the newly created notification.
 131     // |options|: The content of the notification: type, title, message etc.
 132     static void onCreated(DOMString notifierId,
 133                           DOMString notificationId,
 134                           notifications.NotificationOptions options);
 135
 136     // A notification is updated by the notifier.
 137     // |notifierId|: The id of the notifier that sent the updated notification.
 138     // |notificationId|: The id of the updated notification.
 139     // |options|: The content of the notification: type, title, message etc.
 140     static void onUpdated(DOMString notifierId,
 141                           DOMString notificationId,
 142                           notifications.NotificationOptions options);
 143
 144     // A notification is cleared by the notifier.
 145     // |notifierId|: The id of the notifier that cleared the notification.
 146     // |notificationId|: The id of the cleared notification.
 147     static void onCleared(DOMString notifierId, DOMString notificationId);
 148   };
 149 };