Implement pepper interface and plumbing for HRD's UI on ChromeOS

ppapi/api/private/ppb_talk_private.idl

 /* Copyright (c) 2012 The Chromium Authors. All rights reserved.
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
 /**
- * This file contains the <code>PPB_Talk</code> interface.
+ * This file contains the <code>PPB_Talk_Private</code> interface.
  */
 label Chrome {
-  M19 = 1.0
+  M19 = 1.0,
+  M29 = 2.0
 };
 
 /**
+ * The type of permissions that can be requested from the user.
+ */
+[assert_size(4)]
+enum PP_TalkPermission {
+  /**
+   * Request permission for screencast.
+   */
+  PP_TALKPERMISSION_SCREENCAST = 0,
+  /**
+   * Request permission for Remote Desktop.
+   */
+  PP_TALKPERMISSION_REMOTING = 1,
+  /**
+   * Request permission for continuing Remote Desktop.
+   */
+  PP_TALKPERMISSION_REMOTING_CONTINUE = 2
+};
+
+/**
+ * Talk event types reported by the browser.
+ */
+[assert_size(4)]
+enum PP_TalkEvent {
+  /**
+   * Indicates that the user took action to terminate the remoting session.
+   */
+  PP_TALKEVENT_TERMINATE = 0,
+  /**
+   * Indicates that an error occurred (e.g. failed to show the UI).
+   */
+  PP_TALKEVENT_ERROR = 1
+};
+
+/**
+ * Callback for Talk events.
+ */
+typedef void PP_TalkEventCallback([inout] mem_t user_data,
+                                  [in] PP_TalkEvent event);
+
+/**
  * Extra interface for Talk.
  */
 interface PPB_Talk_Private {
   /**
    * Creates a Talk_Private resource.
    */
+  [version=1.0]
   PP_Resource Create(PP_Instance instance);
 
   /**
-   * Displays security UI.
+   * Displays confirmation dialog for screencasting.
    *
    * The callback will be issued with 1 as the result if the user gave
    * permission, or 0 if the user denied.
    *
    * You can only have one call pending. It will return PP_OK_COMPLETIONPENDING
    * if the request is queued, or PP_ERROR_INPROGRESS if there is already a
    * request in progress.
+   *
+   * (Deprecated in 2.0. Please us RequestPermission instead.)
+   */
+  [version=1.0, deprecate=2.0]
+  int32_t GetPermission(
+      [in] PP_Resource talk_resource,
+      [in] PP_CompletionCallback callback);
+
+  /**
+   * Requests permission from the user using a system modal dialog.
+   *
+   * <code>permission</code> specifies the type of permission to request from
+   * the user.
+   *
+   * The callback will be issued with 1 as the result if the user gave
+   * permission, or 0 if the user denied.

[dmichael (off chromium), 2013/06/05 02:11:11]

0 is PP_OK, which usually means success. Since you're changing the interface, it
might be a good time to make it more like everything else. What about PP_OK and
PP_ERROR_NOACCESS? This would match how PPB_MouseLock responds based on user
permission.

[dcaiafa, 2013/06/05 18:49:32]

It would make things more complicated on both sides.  |GetPermission()| is
implemented as a wrapper around
|RequestPermission(PP_TALKPERMISSION_SCREENCAST)|. Different result codes will
require translation on the proxy. On the plugin side, both interfaces will need
to be supported (at least initially), with a fallback to the 1.0 interface. The
different result codes will complicate the code there too.

These are not a huge deal, but they do increase the code complexity a little
(and the potential for bugs). But I don't feel strongly against it. Let me know
if you still prefer the new codes and I'll do it.

Also, please note that these APIs are temporary and will be deleted (not just
deprecated) when WebRTC comes up. This is as certain as anything can be. The
only reason we're even doing this work (instead of just waiting for WebRTC) is
because we have important business reasons to launch this feature on CrOS right
now.

On 2013/06/05 02:11:11, dmichael wrote:

+   *
+   * You can only have one call pending. It will return PP_OK_COMPLETIONPENDING
+   * if the request is queued, or PP_ERROR_INPROGRESS if there is already a
+   * request in progress.
    */
-  int32_t GetPermission(
+  [version=2.0]
+  int32_t RequestPermission(
       [in] PP_Resource talk_resource,
+      [in] PP_TalkPermission permission,
       [in] PP_CompletionCallback callback);
+
+  /**
+   * Shows the remoting-in-progress UI and registers a callback for events.
+   * This function executes synchronously. Returns PP_OK if there were no

[dmichael (off chromium), 2013/06/05 02:11:11]

Do you mean asynchronously?

[dcaiafa, 2013/06/05 18:49:32]

I do mean synchronously. This API shows the in-session remoting UI (actionable
notification and item on the system tray menu). It is modeless, and it will be
available until the plugin calls |StopRemoting()| or the resource is deleted.

On 2013/06/05 02:11:11, dmichael wrote:

[dmichael (off chromium), 2013/06/05 21:02:13]

Can you clarify what you mean by "synchronously", then? I was a bit confused by
it; it's not clear to me what it has to do before returning. It's not actually
blocking and spinning up a nested loop or something, right? You just mean that
when StartRemoting returns, you know that the UI has been displayed?

Also, you appear to be using an asynchronous message. So regardless of what the
host does, it seems like it will behave asynchronously from the plugin's
perspective. Am I misunderstanding something?

[dcaiafa, 2013/06/06 01:24:32]

You are right, it is confusing. I decided to make Start/StopRemoting
asynchronous for consistency. The plugin really wants to know if the UI was
successfully shown before starting a remoting session.

On 2013/06/05 21:02:13, dmichael wrote:

+   * errors.
+   *
+   * This must be called on the pepper main thread. Similarly, |event_callback|
+   * will be called on the pepper main thread.
+   */
+  [version=2.0]
+  int32_t StartRemoting(
+      [in] PP_Resource talk_resource,
+      [in] PP_TalkEventCallback event_callback,

[dmichael (off chromium), 2013/06/05 02:11:11]

Is there some reason you can't use PP_CompletionCallback with a PP_TalkEvent
out-param? Or better still, just user the error code and pick some reasonable
errors from pp_errors.h.

Or is this going to get called more than once?

[dcaiafa, 2013/06/05 18:49:32]

It can be called more than once, although in practice it probably won't since
the plugin will call |StopRemoting()| when it receives a TERMINATE or ERROR
event. It can also not be called at all (if the session is terminated through
other mechanisms). We have been discussing adding more features to the remoting
session UI like a button to toggle keyboard or mouse-clicks off, in which case
multiple events per session would be a more common scenario (although these will
not be seriously considered before the transition to WebRTC). 
 
On 2013/06/05 02:11:11, dmichael wrote:

+      [inout] mem_t user_data);
+
+  /**
+   * Hides the remoting-in-progress UI and unregisters the event callback.
+   *
+   * This must be called on the pepper main thread. Any pending notifications
+   * will be discarded.
+   */
+  [version=2.0]
+  void StopRemoting(
+      [in] PP_Resource talk_resource);
 };