Cleanup in the file chooser API.

This revs the file chooser interface to no longer pass a separate options structure. This structure was weird because it only had two members, and didn't have ownership of the string which is potentially dangerous. The new interface is a bit easier to call.

I changed the string to take a Var, and the C++ layer now takes an Instance*
rather than an Instance& which is consistent with the other interfaces. I
updated the example.

TEST=manual
BUG=

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

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

1 files changed, 70 insertions, 40 deletions

diff --git a/ppapi/c/dev/ppb_file_chooser_dev.h b/ppapi/c/dev/ppb_file_chooser_dev.h
index 27080fe..9199309 100644
--- a/ppapi/c/dev/ppb_file_chooser_dev.h
+++ b/ppapi/c/dev/ppb_file_chooser_dev.h
@@ -13,58 +13,88 @@
 struct PP_CompletionCallback;
 
 typedef enum {
-  PP_FILECHOOSERMODE_OPEN,
-  PP_FILECHOOSERMODE_OPENMULTIPLE
+  PP_FILECHOOSERMODE_OPEN = 0,
+  PP_FILECHOOSERMODE_OPENMULTIPLE = 1
   // TODO(darin): Should there be a way to choose a directory?
 } PP_FileChooserMode_Dev;
 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_FileChooserMode_Dev, 4);
 
-struct PP_FileChooserOptions_Dev {
-  PP_FileChooserMode_Dev mode;
-
-  // A comma-separated list of MIME types such as audio/*,text/plain.  The
-  // dialog may restrict selectable files to the specified MIME types. Null 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.
-  const char* accept_mime_types;
-};
-
-#define PPB_FILECHOOSER_DEV_INTERFACE_0_4 "PPB_FileChooser(Dev);0.4"
-#define PPB_FILECHOOSER_DEV_INTERFACE PPB_FILECHOOSER_DEV_INTERFACE_0_4
+#define PPB_FILECHOOSER_DEV_INTERFACE_0_5 "PPB_FileChooser(Dev);0.5"
+#define PPB_FILECHOOSER_DEV_INTERFACE PPB_FILECHOOSER_DEV_INTERFACE_0_5
 
 struct PPB_FileChooser_Dev {
-  // Creates a file chooser dialog with the specified options.  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.
-  //
-  // 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.
+  /**
+   * 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.
+   *
+   * @param 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.
+   */
   PP_Resource (*Create)(PP_Instance instance,
-                        const struct PP_FileChooserOptions_Dev* options);
+                        PP_FileChooserMode_Dev mode,
+                        struct PP_Var accept_mime_types);
 
-  // Returns PP_TRUE if the given resource is a FileChooser. Returns PP_FALSE
-  // if the resource is invalid or some type other than a FileChooser.
+  /**
+   * 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.
+   */
   PP_Bool (*IsFileChooser)(PP_Resource resource);
 
-  // Prompts 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.
+  /**
+   * 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.
+   *
+   * @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 call to 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 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.
+  /**
+   * 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.
+   */
+  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);
 };