Create IDL for PPB_FileChooser_Dev and PPB_FileChooser_Trusted, and add the ability to run

the filedialog in "Save As" mode.
BUG=73070
TEST=none yet
Review URL: http://codereview.chromium.org/8116018

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

4 files changed, 271 insertions, 45 deletions

diff --git a/ppapi/api/dev/ppb_file_chooser_dev.idl b/ppapi/api/dev/ppb_file_chooser_dev.idl
new file mode 100644
index 0000000..9de33dc
--- /dev/null
+++ b/ppapi/api/dev/ppb_file_chooser_dev.idl
@@ -0,0 +1,111 @@
+/* Copyright (c) 2011 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 defines the <code>PPB_FileChooser_Dev</code> interface.
+ */
+
+label Chrome {
+  M16 = 0.5
+};
+
+/**
+ * This enumeration contains constants to control the behavior of the file
+ * chooser dialog.
+ */
+[assert_size(4)]
+enum PP_FileChooserMode_Dev {
+  /**
+   * Mode for choosing a single existing file.
+   */
+  PP_FILECHOOSERMODE_OPEN = 0,
+  /**
+   * Mode for choosing multiple existing files.
+   */
+  PP_FILECHOOSERMODE_OPENMULTIPLE,
+  /**
+   * Mode for choosing a file for saving. If the user selects a file that
+   * doesn't exist, it will be created.
+   */
+  PP_FILECHOOSERMODE_SAVE
+};
+
+interface PPB_FileChooser_Dev {
+ /**
+  * This function creates a file chooser dialog resource.  The chooser is
+  * associated with a particular instance, so that it may be positioned on the
+  * screen relative to the tab containing the instance.
+  *
+  * @param[in] instance A <code>PP_Instance</code> identifying one instance
+  * of a module.
+  * @param[in] mode A <code>PP_FileChooserMode_Dev</code> value that controls
+  * the behavior of the file chooser dialog.
+  * @param[in] accept_mime_types A comma-separated list of MIME types such as
+  * "audio/ *,text/plain" (note there should be no space between the '/' and
+  * the '*', but one is added to avoid confusing C++ comments).  The dialog
+  * may restrict selectable files to the specified MIME types. An empty string
+  * or an undefined var may be given to indicate that all types should be
+  * accepted.
+  *
+  * @return A <code>PP_Resource</code> containing the file chooser if
+  * successful or 0 if it could not be created.
+  */
+  PP_Resource Create(
+      [in] PP_Instance instance,
+      [in] PP_FileChooserMode_Dev mode,
+      [in] PP_Var accept_mime_types);
+
+  /**
+   * Determines if the provided resource is a file chooser.
+   *
+   * @param[in] resource A <code>PP_Resource</code> corresponding to a generic
+   * resource.
+   *
+   * @return A <code>PP_Bool</code> containing containing <code>PP_TRUE</code>
+   * if the given resource is a file chooser resource, otherwise
+   * <code>PP_FALSE</code>.
+   */
+  PP_Bool IsFileChooser(
+      [in] PP_Resource resource);
+
+  /**
+   * This function displays a previously created file chooser resource as a
+   * dialog box, prompting the user to choose a file or files. This function
+   * must be called in response to an input event that is a user gesture, such
+   * as a mouse click or touch event. The callback is called with PP_OK on
+   * successful completion with a file (or files) selected, PP_ERROR_USERCANCEL
+   * if the user selected no file, or another error code from pp_errors.h on
+   * failure.
+   *
+   * @param[in] chooser The file chooser resource.
+   * @param[in] callback A <code>CompletionCallback</code> to be called after
+   * the user has closed the file chooser dialog.
+   *
+   * @return PP_OK_COMPLETIONPENDING if request to show the dialog was
+   * successful, another error code from pp_errors.h on failure.
+   */
+  int32_t Show(
+      [in] PP_Resource chooser,
+      [in] PP_CompletionCallback callback);
+
+  /**
+   * After a successful completion callback call from Show, this method may be
+   * used to query the chosen files.  It should be called in a loop until it
+   * returns 0.  Depending on the PP_ChooseFileMode_Dev requested when the
+   * FileChooser was created, the file refs will either be readable or
+   * writable.  Their file system type will be PP_FileSystemType_External.  If
+   * the user chose no files or cancelled the dialog, then this method will
+   * simply return 0 the first time it is called.
+   *
+   * @param[in] chooser The file chooser resource.
+   *
+   * @return A <code>PP_Resource</code> containing the next file chosen by the
+   * user, or 0 if there are no more files.
+   */
+  PP_Resource GetNextChosenFile(
+      [in] PP_Resource chooser);
+};
+
diff --git a/ppapi/api/trusted/ppb_file_chooser_trusted.idl b/ppapi/api/trusted/ppb_file_chooser_trusted.idl
new file mode 100644
index 0000000..97624c8
--- /dev/null
+++ b/ppapi/api/trusted/ppb_file_chooser_trusted.idl
@@ -0,0 +1,33 @@
+/* Copyright (c) 2011 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 defines the <code>PPB_FileChooser_Trusted</code> interface.
+ */
+
+label Chrome {
+  M16 = 0.5
+};
+
+interface PPB_FileChooser_Trusted {
+  /**
+   * This function displays a previously created file chooser resource as a
+   * dialog box, prompting the user to choose a file or files. The callback is
+   * called with PP_OK on successful completion with a file (or files) selected
+   * or PP_ERROR_USERCANCEL if the user selected no file.
+   *
+   * @param[in] chooser The file chooser resource.
+   * @param[in] callback A <code>CompletionCallback</code> to be called after
+   * the user has closed the file chooser dialog.
+   *
+   * @return PP_OK_COMPLETIONPENDING if request to show the dialog was
+   * successful, another error code from pp_errors.h on failure.
+   */
+  int32_t ShowWithoutUserGesture(
+      [in] PP_Resource chooser,
+      [in] PP_CompletionCallback callback);
+};
+
diff --git a/ppapi/c/dev/ppb_file_chooser_dev.h b/ppapi/c/dev/ppb_file_chooser_dev.h
index 9199309..58a5aa5 100644
--- a/ppapi/c/dev/ppb_file_chooser_dev.h
+++ b/ppapi/c/dev/ppb_file_chooser_dev.h
@@ -2,73 +2,112 @@
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
+
+/* From dev/ppb_file_chooser_dev.idl modified Tue Oct 04 13:39:06 2011. */
+
 #ifndef PPAPI_C_DEV_PPB_FILE_CHOOSER_DEV_H_
 #define PPAPI_C_DEV_PPB_FILE_CHOOSER_DEV_H_
 
 #include "ppapi/c/pp_bool.h"
+#include "ppapi/c/pp_completion_callback.h"
 #include "ppapi/c/pp_instance.h"
 #include "ppapi/c/pp_macros.h"
 #include "ppapi/c/pp_resource.h"
+#include "ppapi/c/pp_stdint.h"
+#include "ppapi/c/pp_var.h"
+
+#define PPB_FILECHOOSER_DEV_INTERFACE_0_5 "PPB_FileChooser(Dev);0.5"
+#define PPB_FILECHOOSER_DEV_INTERFACE PPB_FILECHOOSER_DEV_INTERFACE_0_5
 
-struct PP_CompletionCallback;
+/**
+ * @file
+ * This file defines the <code>PPB_FileChooser_Dev</code> interface.
+ */
 
+
+/**
+ * @addtogroup Enums
+ * @{
+ */
+/**
+ * This enumeration contains constants to control the behavior of the file
+ * chooser dialog.
+ */
 typedef enum {
+  /**
+   * Mode for choosing a single existing file.
+   */
   PP_FILECHOOSERMODE_OPEN = 0,
-  PP_FILECHOOSERMODE_OPENMULTIPLE = 1
-  // TODO(darin): Should there be a way to choose a directory?
+  /**
+   * Mode for choosing multiple existing files.
+   */
+  PP_FILECHOOSERMODE_OPENMULTIPLE,
+  /**
+   * Mode for choosing a file for saving. If the user selects a file that
+   * doesn't exist, it will be created.
+   */
+  PP_FILECHOOSERMODE_SAVE
 } PP_FileChooserMode_Dev;
 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_FileChooserMode_Dev, 4);
+/**
+ * @}
+ */
 
-#define PPB_FILECHOOSER_DEV_INTERFACE_0_5 "PPB_FileChooser(Dev);0.5"
-#define PPB_FILECHOOSER_DEV_INTERFACE PPB_FILECHOOSER_DEV_INTERFACE_0_5
-
+/**
+ * @addtogroup Interfaces
+ * @{
+ */
 struct PPB_FileChooser_Dev {
   /**
    * This function creates a file chooser dialog resource.  The chooser is
    * associated with a particular instance, so that it may be positioned on the
-   * screen relative to the tab containing the instance.  Returns 0 if passed
-   * an invalid instance.
-   *
-   * @param mode A PPB_FileChooser_Dev instance can be used to select a single
-   * file (PP_FILECHOOSERMODE_OPEN) or multiple files
-   * (PP_FILECHOOSERMODE_OPENMULTIPLE). Unlike the HTML5 <input type="file">
-   * tag, a PPB_FileChooser_Dev instance cannot be used to select a directory.
-   * In order to get the list of files in a directory, the
-   * PPB_DirectoryReader_Dev interface must be used.
+   * screen relative to the tab containing the instance.
    *
-   * @param accept_mime_types A comma-separated list of MIME types such as
+   * @param[in] instance A <code>PP_Instance</code> identifying one instance
+   * of a module.
+   * @param[in] mode A <code>PP_FileChooserMode_Dev</code> value that controls
+   * the behavior of the file chooser dialog.
+   * @param[in] accept_mime_types A comma-separated list of MIME types such as
    * "audio/ *,text/plain" (note there should be no space between the '/' and
    * the '*', but one is added to avoid confusing C++ comments).  The dialog
    * may restrict selectable files to the specified MIME types. An empty string
    * or an undefined var may be given to indicate that all types should be
    * accepted.
    *
-   * TODO(darin): What if the mime type is unknown to the system?  The plugin
-   * may wish to describe the mime type and provide a matching file extension.
-   * It is more webby to use mime types here instead of file extensions.
+   * @return A <code>PP_Resource</code> containing the file chooser if
+   * successful or 0 if it could not be created.
    */
   PP_Resource (*Create)(PP_Instance instance,
                         PP_FileChooserMode_Dev mode,
                         struct PP_Var accept_mime_types);
-
   /**
-   * IsFileChooser returns PP_TRUE if the given resource is a FileChooser.
-   * It returns PP_FALSE if the resource is invalid or some type other than a
-   * FileChooser.
+   * Determines if the provided resource is a file chooser.
+   *
+   * @param[in] resource A <code>PP_Resource</code> corresponding to a generic
+   * resource.
+   *
+   * @return A <code>PP_Bool</code> containing containing <code>PP_TRUE</code>
+   * if the given resource is a file chooser resource, otherwise
+   * <code>PP_FALSE</code>.
    */
   PP_Bool (*IsFileChooser)(PP_Resource resource);
-
   /**
    * This function displays a previously created file chooser resource as a
-   * dialog box, prompting the user to choose a file or files. The callback is
-   * called with PP_OK on successful completion with a file (or files) selected
-   * or PP_ERROR_USERCANCEL if the user selected no file.
+   * dialog box, prompting the user to choose a file or files. This function
+   * must be called in response to an input event that is a user gesture, such
+   * as a mouse click or touch event. The callback is called with PP_OK on
+   * successful completion with a file (or files) selected, PP_ERROR_USERCANCEL
+   * if the user selected no file, or another error code from pp_errors.h on
+   * failure.
+   *
+   * @param[in] chooser The file chooser resource.
+   * @param[in] callback A <code>CompletionCallback</code> to be called after
+   * the user has closed the file chooser dialog.
    *
    * @return PP_OK_COMPLETIONPENDING if request to show the dialog was
    * successful, another error code from pp_errors.h on failure.
    */
   int32_t (*Show)(PP_Resource chooser, struct PP_CompletionCallback callback);
-
   /**
    * After a successful completion callback call from Show, this method may be
    * used to query the chosen files.  It should be called in a loop until it
@@ -77,25 +116,17 @@ struct PPB_FileChooser_Dev {
    * writable.  Their file system type will be PP_FileSystemType_External.  If
    * the user chose no files or cancelled the dialog, then this method will
    * simply return 0 the first time it is called.
+   *
+   * @param[in] chooser The file chooser resource.
+   *
+   * @return A <code>PP_Resource</code> containing the next file chosen by the
+   * user, or 0 if there are no more files.
    */
   PP_Resource (*GetNextChosenFile)(PP_Resource chooser);
 };
-
-// Deprecated 0.4 version ------------------------------------------------------
-
-#define PPB_FILECHOOSER_DEV_INTERFACE_0_4 "PPB_FileChooser(Dev);0.4"
-
-struct PP_FileChooserOptions_0_4_Dev {
-  PP_FileChooserMode_Dev mode;
-  const char* accept_mime_types;
-};
-
-struct PPB_FileChooser_0_4_Dev {
-  PP_Resource (*Create)(PP_Instance instance,
-                        const struct PP_FileChooserOptions_0_4_Dev* options);
-  PP_Bool (*IsFileChooser)(PP_Resource resource);
-  int32_t (*Show)(PP_Resource chooser, struct PP_CompletionCallback callback);
-  PP_Resource (*GetNextChosenFile)(PP_Resource chooser);
-};
+/**
+ * @}
+ */
 
 #endif  /* PPAPI_C_DEV_PPB_FILE_CHOOSER_DEV_H_ */
+
diff --git a/ppapi/c/trusted/ppb_file_chooser_trusted.h b/ppapi/c/trusted/ppb_file_chooser_trusted.h
new file mode 100644
index 0000000..5992281
--- /dev/null
+++ b/ppapi/c/trusted/ppb_file_chooser_trusted.h
@@ -0,0 +1,51 @@
+/* Copyright (c) 2011 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.
+ */
+
+/* From trusted/ppb_file_chooser_trusted.idl modified Tue Oct 04 10:48:17 2011. */
+
+#ifndef PPAPI_C_TRUSTED_PPB_FILE_CHOOSER_TRUSTED_H_
+#define PPAPI_C_TRUSTED_PPB_FILE_CHOOSER_TRUSTED_H_
+
+#include "ppapi/c/pp_completion_callback.h"
+#include "ppapi/c/pp_macros.h"
+#include "ppapi/c/pp_resource.h"
+#include "ppapi/c/pp_stdint.h"
+
+#define PPB_FILECHOOSER_TRUSTED_INTERFACE_0_5 "PPB_FileChooser_Trusted;0.5"
+#define PPB_FILECHOOSER_TRUSTED_INTERFACE PPB_FILECHOOSER_TRUSTED_INTERFACE_0_5
+
+/**
+ * @file
+ * This file defines the <code>PPB_FileChooser_Trusted</code> interface.
+ */
+
+
+/**
+ * @addtogroup Interfaces
+ * @{
+ */
+struct PPB_FileChooser_Trusted {
+  /**
+   * This function displays a previously created file chooser resource as a
+   * dialog box, prompting the user to choose a file or files. The callback is
+   * called with PP_OK on successful completion with a file (or files) selected
+   * or PP_ERROR_USERCANCEL if the user selected no file.
+   *
+   * @param[in] chooser The file chooser resource.
+   * @param[in] callback A <code>CompletionCallback</code> to be called after
+   * the user has closed the file chooser dialog.
+   *
+   * @return PP_OK_COMPLETIONPENDING if request to show the dialog was
+   * successful, another error code from pp_errors.h on failure.
+   */
+  int32_t (*ShowWithoutUserGesture)(PP_Resource chooser,
+                                    struct PP_CompletionCallback callback);
+};
+/**
+ * @}
+ */
+
+#endif  /* PPAPI_C_TRUSTED_PPB_FILE_CHOOSER_TRUSTED_H_ */
+