ppapi/api/trusted/ppb_broker_trusted.idl

   1 /* Copyright (c) 2012 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
   6 /**
   7  * This file defines the PPB_BrokerTrusted interface, which provides
   8  * access to a trusted broker with greater privileges than the plugin.
   9  */
  10
  11 label Chrome {
  12   M14 = 0.2,
  13   M25 = 0.3
  14 };
  15
  16 /**
  17  * The PPB_BrokerTrusted interface provides access to a trusted broker
  18  * with greater privileges than the plugin. The interface only supports
  19  * out-of-process plugins and is to be used by proxy implementations.  All
  20  * functions should be called from the main thread only.
  21  *
  22  * A PPB_BrokerTrusted resource represents a connection to the broker. Its
  23  * lifetime controls the lifetime of the broker, regardless of whether the
  24  * handle is closed. The handle should be closed before the resource is
  25  * released.
  26  */
  27 [macro="PPB_BROKER_TRUSTED_INTERFACE"]
  28 interface PPB_BrokerTrusted {
  29   /**
  30    * Returns a trusted broker resource.
  31    */
  32   PP_Resource CreateTrusted([in] PP_Instance instance);
  33
  34   /**
  35    * Returns true if the resource is a trusted broker.
  36    */
  37   PP_Bool IsBrokerTrusted([in] PP_Resource resource);
  38
  39   /**
  40    * Connects to the trusted broker. It may have already
  41    * been launched by another instance.
  42    * The plugin takes ownership of the handle once the callback has been called
  43    * with a result of PP_OK. The plugin should immediately call GetHandle and
  44    * begin managing it. If the result is not PP_OK, the browser still owns the
  45    * handle.
  46    *
  47    * Returns PP_ERROR_WOULD_BLOCK on success, and invokes
  48    * the |connect_callback| asynchronously to complete.
  49    * As this function should always be invoked from the main thread,
  50    * do not use the blocking variant of PP_CompletionCallback.
  51    * Returns PP_ERROR_FAILED if called from an in-process plugin.
  52    */
  53   int32_t Connect([in] PP_Resource broker,
  54                   [in] PP_CompletionCallback connect_callback);
  55
  56   /**
  57    * Gets the handle to the pipe. Use once Connect has completed. Each instance
  58    * of this interface has its own pipe.
  59    *
  60    * Returns PP_OK on success, and places the result into the given output
  61    * parameter. The handle is only set when returning PP_OK. Calling this
  62    * before connect has completed will return PP_ERROR_FAILED.
  63    */
  64   int32_t GetHandle([in] PP_Resource broker, [out] int32_t handle);
  65
  66   /**
  67    * Returns PP_TRUE if the plugin has permission to launch the broker. A user
  68    * must explicitly grant permission to launch the broker for a particular
  69    * website. This is done through an infobar that is displayed when |Connect|
  70    * is called. This function returns PP_TRUE if the user has already granted
  71    * permission to launch the broker for the website containing this plugin
  72    * instance. Returns PP_FALSE otherwise.
  73    */
  74   [version=0.3]
  75   PP_Bool IsAllowed([in] PP_Resource broker);
  76 };
  77