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
11label 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"]
28interface 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
78