toolkit/mozapps/defaultagent/nsIDefaultAgent.idl

   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 [scriptable, uuid(edc38cb5-b6f6-4aeb-bd45-7be8e00fc364)]
   9 interface nsIDefaultAgent : nsISupports
  10 {
  11   /**
  12   * Create a Windows scheduled task that will launch this binary with the
  13   * do-task command every 24 hours, starting from 24 hours after register-task
  14   * is run.
  15   *
  16   * @param {AString} aUniqueToken
  17   *        A unique identifier for this installation; typically the install path
  18   *        hash that's used for the update directory, the AppUserModelID, and
  19   *        other related purposes.
  20   */
  21   void registerTask(in AString aUniqueToken);
  22
  23   /**
  24   * Update an existing task registration, without changing its schedule. This
  25   * should be called during updates of the application, in case this program
  26   * has been updated and any of the task parameters have changed.
  27   *
  28   * @param {AString} aUniqueToken
  29   *        A unique identifier for this installation; the same one provided when
  30   *        the task was registered.
  31   */
  32   void updateTask(in AString aUniqueToken);
  33
  34   /**
  35   * Removes the previously created task. The unique token argument is required
  36   * and should be the same one that was passed in when the task was registered.
  37   *
  38   * @param {AString} aUniqueToken
  39   *        A unique identifier for this installation; the same one provided when
  40   *        the task was registered.
  41   */
  42   void unregisterTask(in AString aUniqueToken);
  43
  44   /**
  45   * Removes the previously created task, and also removes all registry entries
  46   * running the task may have created.
  47   *
  48   * @param {AString} aUniqueToken
  49   *        A unique identifier for this installation; the same one provided when
  50   *        the task was registered.
  51   */
  52   void uninstall(in AString aUniqueToken);
  53
  54   /**
  55   * Actually performs the default agent task, which currently means generating
  56   * and sending our telemetry ping and possibly showing a notification to the
  57   * user if their browser has switched from Firefox to Edge with Blink.
  58   *
  59   * @param {AString} aUniqueToken
  60   *        A unique identifier for this installation; the same one provided when
  61   *        the task was registered.
  62   * @param {boolean} aForce
  63   *        For debugging, forces the task to run even if it has run in the last
  64   *        24 hours, and forces the notification to show.
  65   */
  66   void doTask(in AString aUniqueToken, in boolean aForce);
  67
  68   /**
  69   * Checks that the main app ran recently.
  70   *
  71   * @return {boolean} true if the app ran recently.
  72   */
  73   boolean appRanRecently();
  74
  75   /**
  76   * Returns a string for the default browser if known, binned to known browsers.
  77   *
  78   * @return {AString}
  79   *         The current default browser.
  80   */
  81   AString getDefaultBrowser();
  82
  83   /**
  84   * Gets and replaces the previously found default browser from the registry.
  85   *
  86   * @param {AString} aCurrentBrowser
  87   *        The current known browser to save to the registry.
  88   * @return {AString}
  89   *         The previous known browser from the registry.
  90   */
  91   AString getReplacePreviousDefaultBrowser(in AString aCurrentBrowser);
  92
  93   /**
  94   * Returns a string for the default PDF handler if known, binned to known
  95   * PDF handlers.
  96   *
  97   * @return {AString}
  98   *         The previous default PDF handler.
  99   */
 100   AString getDefaultPdfHandler();
 101
 102   /**
 103   * Sends a Default Agent telemetry ping.
 104   *
 105   * @param {AString} aCurrentBrowser
 106   *        The current known browser.
 107   * @param {AString} aPreviousBrowser
 108   *        The previous known browser.
 109   * @param {AString} aPdfHandler
 110   *        The current known PDF handler.
 111   * @param {AString} aNotificationShown
 112   *        If the notification was or wasn't shown. See
 113   *        `toolkit/mozapps/defaultagent/Notification.h` for valid values.
 114   * @param {AString} aNotificationAction
 115   *        The notification action taken by the user. See
 116   *        `toolkit/mozapps/defaultagent/Notification.h` for valid values.
 117   *
 118   */
 119   void sendPing(in AString aCurrentBrowser, in AString aPreviousBrowser, in AString aPdfHandler, in AString aNotificationShown, in AString aNotificationAction);
 120
 121   /**
 122   * Set the default browser and optionally additional file extensions via the
 123   * UserChoice registry keys.
 124   *
 125   * @param {AString} aAumid
 126   *        Suffix to be appended to ProgIDs when registering system defaults.
 127   * @param {Array<AString>} aExtraFileExtensions
 128   *        Additional optional file extensions to register specified as argument
 129   *        pairs: the first element is the file extension, the second element is
 130   *        the root of a ProgID, which will be suffixed with `-{aAumid}`.
 131   */
 132   void setDefaultBrowserUserChoice(in AString aAumid, in Array<AString> aExtraFileExtensions);
 133
 134   /**
 135   * Set the default browser and optionally additional file extensions via the
 136   * UserChoice registry keys, asynchronously. Does the actual work on a
 137   * background thread.
 138   *
 139   * @param {AString} aAumid
 140   *        Suffix to be appended to ProgIDs when registering system defaults.
 141   * @param {Array<AString>} aExtraFileExtensions
 142   *        Additional optional file extensions to register specified as argument
 143   *        pairs: the first element is the file extension, the second element is
 144   *        the root of a ProgID, which will be suffixed with `-{aAumid}`.
 145   */
 146   [implicit_jscontext]
 147   Promise setDefaultBrowserUserChoiceAsync(in AString aAumid, in Array<AString> aExtraFileExtensions);
 148
 149   /**
 150   * Sets file extensions via the UserChoice registry keys.
 151   *
 152   * @param {AString} aAumid
 153   *        Suffix to be appended to ProgIDs when registering system defaults.
 154   * @param {Array<AString>} aExtraFileExtensions
 155   *        File extensions to register specified as argument pairs: the first
 156   *        element is the file extension, the second element is the root of a
 157   *        ProgID, which will be suffixed with `-{aAumid}`.
 158   */
 159   void setDefaultExtensionHandlersUserChoice(in AString aAumid, in Array<AString> aFileExtensions);
 160
 161   /**
 162   * Checks if the default agent has been disabled.
 163   *
 164   * @return {boolean} true if the default agent is disabled.
 165   */
 166   boolean agentDisabled();
 167 };