15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/* Copyright (c) 2012 The Chromium Authors. All rights reserved.
25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * Use of this source code is governed by a BSD-style license that can be
35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * found in the LICENSE file.
45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */
55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/**
75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * This file defines the PPB_BrokerTrusted interface, which provides
85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * access to a trusted broker with greater privileges than the plugin.
95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */
105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)label Chrome {
122a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)  M14 = 0.2,
132a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)  M25 = 0.3
145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)};
155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/**
175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * The PPB_BrokerTrusted interface provides access to a trusted broker
185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * with greater privileges than the plugin. The interface only supports
195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * out-of-process plugins and is to be used by proxy implementations.  All
205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * functions should be called from the main thread only.
215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) *
225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * A PPB_BrokerTrusted resource represents a connection to the broker. Its
235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * lifetime controls the lifetime of the broker, regardless of whether the
245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * handle is closed. The handle should be closed before the resource is
255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) * released.
265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) */
275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)[macro="PPB_BROKER_TRUSTED_INTERFACE"]
285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)interface PPB_BrokerTrusted {
295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  /**
305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   * Returns a trusted broker resource.
315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   */
325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  PP_Resource CreateTrusted([in] PP_Instance instance);
335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  /**
355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   * Returns true if the resource is a trusted broker.
365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   */
375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  PP_Bool IsBrokerTrusted([in] PP_Resource resource);
385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  /**
405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   * Connects to the trusted broker. It may have already
415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   * been launched by another instance.
425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   * The plugin takes ownership of the handle once the callback has been called
435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   * with a result of PP_OK. The plugin should immediately call GetHandle and
445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   * begin managing it. If the result is not PP_OK, the browser still owns the
455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   * handle.
465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   *
475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   * Returns PP_ERROR_WOULD_BLOCK on success, and invokes
485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   * the |connect_callback| asynchronously to complete.
495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   * As this function should always be invoked from the main thread,
505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   * do not use the blocking variant of PP_CompletionCallback.
515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   * Returns PP_ERROR_FAILED if called from an in-process plugin.
525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   */
535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  int32_t Connect([in] PP_Resource broker,
545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)                  [in] PP_CompletionCallback connect_callback);
555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  /**
575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   * Gets the handle to the pipe. Use once Connect has completed. Each instance
585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   * of this interface has its own pipe.
595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   *
605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   * Returns PP_OK on success, and places the result into the given output
615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   * parameter. The handle is only set when returning PP_OK. Calling this
625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   * before connect has completed will return PP_ERROR_FAILED.
635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)   */
645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)  int32_t GetHandle([in] PP_Resource broker, [out] int32_t handle);
652a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)
662a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)  /**
672a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)   * Returns PP_TRUE if the plugin has permission to launch the broker. A user
682a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)   * must explicitly grant permission to launch the broker for a particular
692a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)   * website. This is done through an infobar that is displayed when |Connect|
702a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)   * is called. This function returns PP_TRUE if the user has already granted
712a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)   * permission to launch the broker for the website containing this plugin
722a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)   * instance. Returns PP_FALSE otherwise.
732a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)   */
742a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)  [version=0.3]
752a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles)  PP_Bool IsAllowed([in] PP_Resource broker);
765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)};
775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)
78