Introduce PPB_Flash_MessageLoop interface for Pepper Flash.

Comparing with PPB_Flash.RunMessageLoop/QuitMessageLoop, this new interface avoids leaking nested message loops. If Quit() is not called to balance the call to Run(), the outermost message loop will be quitted when the resource is destroyed.

BUG=109340
TEST=test_flash_message_loop.{h,cc}


Review URL: http://codereview.chromium.org/9188045

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@119873 0039d316-1c4b-4281-b951-d872f2087c98

1 files changed, 73 insertions, 0 deletions

diff --git a/ppapi/api/private/ppb_flash_message_loop.idl b/ppapi/api/private/ppb_flash_message_loop.idl
new file mode 100644
index 0000000..4874907
--- /dev/null
+++ b/ppapi/api/private/ppb_flash_message_loop.idl
@@ -0,0 +1,73 @@
+/* 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_Flash_MessageLoop</code> interface.
+ */
+
+label Chrome {
+  M18 = 0.1
+};
+
+/**
+ * The <code>PPB_Flash_MessageLoop</code> interface supports Pepper Flash to run
+ * nested message loops.
+ */
+interface PPB_Flash_MessageLoop {
+  /**
+   * Allocates a Flash message loop resource.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying one instance
+   * of a module.
+   *
+   * @return A <code>PP_Resource</code> that can be used to run a nested message
+   * loop if successful; 0 if failed.
+   */
+  PP_Resource Create([in] PP_Instance instance);
+
+  /**
+   * Determines if a given resource is a Flash message loop.
+   *
+   * @param[in] resource A <code>PP_Resource</code> corresponding to a generic
+   * resource.
+   *
+   * @return A <code>PP_Bool</code> that is <code>PP_TRUE</code> if the given
+   * resource is a Flash message loop, otherwise <code>PP_FALSE</code>.
+   */
+  PP_Bool IsFlashMessageLoop([in] PP_Resource resource);
+
+  /**
+   * Runs a nested message loop. The plugin will be reentered from this call.
+   * This function is used in places where Flash would normally enter a nested
+   * message loop (e.g., when displaying context menus), but Pepper provides
+   * only an asynchronous call. After performing that asynchronous call, call
+   * <code>Run()</code>. In the callback, call <code>Quit()</code>.
+   *
+   * For a given message loop resource, only the first call to
+   * <code>Run()</code> will start a nested message loop. The subsequent calls
+   * will return <code>PP_ERROR_FAILED</code> immediately.
+   *
+   * @param[in] flash_message_loop The Flash message loop.
+   *
+   * @return <code>PP_ERROR_ABORTED</code> if the message loop quits because the
+   * resource is destroyed; <code>PP_OK</code> if the message loop quits because
+   * of other reasons (e.g., <code>Quit()</code> is called);
+   * <code>PP_ERROR_FAILED</code> if this is not the first call to
+   * <code>Run()</code>.
+   */
+  int32_t Run([in] PP_Resource flash_message_loop);
+
+  /**
+   * Signals to quit the outermost nested message loop. Use this to exit and
+   * return back to the caller after you call <code>Run()</code>.
+   *
+   * If <code>Quit()</code> is not called to balance the call to
+   * <code>Run()</code>, the outermost nested message loop will be quitted
+   * implicitly when the resource is destroyed.
+   *
+   * @param[in] flash_message_loop The Flash message loop.
+   */
+  void Quit([in] PP_Resource flash_message_loop);
+};
\ No newline at end of file