remote/nsIRemoteAgent.idl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #include "nsISupports.idl"
   6
   7 /**
   8  * The Gecko remote agent is an RPC subsystem that exposes
   9  * browser-internal interfaces and services to the surrounding
  10  * system.
  11  *
  12  * Consumers, whether remote or browser-local, can interface with
  13  * the browser through an assorted set of services ranging from
  14  * document introspection and script evaluation, to instrumentation,
  15  * user interaction simulation, and event subscription.
  16  */
  17 [scriptable, uuid(8f685a9d-8181-46d6-a71d-869289099c6d)]
  18 interface nsIRemoteAgent : nsISupports
  19 {
  20   /**
  21    * Whether the remote agent is currently listening for new,
  22    * incoming connections.
  23    */
  24   readonly attribute boolean listening;
  25
  26   /**
  27    * Asynchronously starts the remote agent, and listens for new
  28    * connections.
  29    *
  30    * The address must be a fully qualified URL that uses the "http://"
  31    * scheme, and can optionally include a desired port.  If no port
  32    * is chosen, the default port 9222 is used.
  33    *
  34    * If the requested port is 0, the system will atomically allocate
  35    * a port.
  36    *
  37    * A "remote-listening" system observer notification with the URL
  38    * of the main target's WebSocket will be emitted once listening.
  39    *
  40    * @throws NS_ERROR_NOT_AVAILABLE
  41    *     When disabled by the remote.enabled preference.
  42    * @throws NS_ERROR_LAUNCHED_CHILD_PROCESS
  43    *     When called from a child process.
  44    * @throws NS_ERROR_ILLEGAL_VALUE
  45    *     If requested to bind to a non-loopback device
  46    *     if remote.force-local is true.
  47    */
  48   void listen(in AString aURL);
  49
  50   /** Stops listening and drops existing connections. */
  51   void close();
  52 };
  53
  54 %{C++
  55 #define NS_REMOTEAGENT_CONTRACTID "@mozilla.org/remote/agent;1"
  56 #define NS_REMOTEAGENT_CID \
  57   { 0x8f685a9d, 0x8181, 0x46d6, \
  58     { 0xa7, 0x1d, x86, x92, x89, x09, x9c, x6d } }
  59 %}