ppapi/api/dev/ppb_file_chooser_dev.idl

   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 /**
   8  * This file defines the <code>PPB_FileChooser_Dev</code> interface.
   9  */
  10
  11 [generate_thunk]
  12
  13 label Chrome {
  14   M16 = 0.5,
  15   M19 = 0.6
  16 };
  17
  18 /**
  19  * This enumeration contains constants to control the behavior of the file
  20  * chooser dialog.
  21  */
  22 [assert_size(4)]
  23 enum PP_FileChooserMode_Dev {
  24   /**
  25    * Mode for choosing a single existing file.
  26    */
  27   PP_FILECHOOSERMODE_OPEN = 0,
  28   /**
  29    * Mode for choosing multiple existing files.
  30    */
  31   PP_FILECHOOSERMODE_OPENMULTIPLE = 1
  32 };
  33
  34 interface PPB_FileChooser_Dev {
  35  /**
  36   * This function creates a file chooser dialog resource.  The chooser is
  37   * associated with a particular instance, so that it may be positioned on the
  38   * screen relative to the tab containing the instance.
  39   *
  40   * @param[in] instance A <code>PP_Instance</code> identifying one instance
  41   * of a module.
  42   * @param[in] mode A <code>PP_FileChooserMode_Dev</code> value that controls
  43   * the behavior of the file chooser dialog.
  44   * @param[in] accept_types A comma-separated list of MIME types and file
  45   * extensions such as "audio/ *,text/plain,.html" (note there should be no
  46   * space between the '/' and the '*', but one is added to avoid confusing C++
  47   * comments). The dialog may restrict selectable files to the specified MIME
  48   * types and file extensions. If a string in the comma-separated list begins
  49   * with a period (.) then the string is interpreted as a file extension,
  50   * otherwise it is interpreted as a MIME-type. An empty string or an undefined
  51   * var may be given to indicate that all types should be accepted.
  52   *
  53   * @return A <code>PP_Resource</code> containing the file chooser if
  54   * successful or 0 if it could not be created.
  55   */
  56   PP_Resource Create(
  57       [in] PP_Instance instance,
  58       [in] PP_FileChooserMode_Dev mode,
  59       [in] PP_Var accept_types);
  60
  61   /**
  62    * Determines if the provided resource is a file chooser.
  63    *
  64    * @param[in] resource A <code>PP_Resource</code> corresponding to a generic
  65    * resource.
  66    *
  67    * @return A <code>PP_Bool</code> that is <code>PP_TRUE</code> if the given
  68    * resource is a file chooser resource, otherwise <code>PP_FALSE</code>.
  69    */
  70   PP_Bool IsFileChooser(
  71       [in] PP_Resource resource);
  72
  73   /**
  74    * This function displays a previously created file chooser resource as a
  75    * dialog box, prompting the user to choose a file or files. This function
  76    * must be called in response to a user gesture, such as a mouse click or
  77    * touch event. The callback is called with PP_OK on successful completion
  78    * with a file (or files) selected, PP_ERROR_USERCANCEL if the user selected
  79    * no file, or another error code from pp_errors.h on failure.
  80    *
  81    * <b>Subtle note:</b> This function will only work when the tab containing
  82    * the plugin is visible. Show will fail if the tab is in the background.
  83    * Since it's not normally possible to get input events while invisible, this
  84    * is not an issue. But there is a race condition because events are
  85    * processed asynchronously that authors should be aware of. If the user
  86    * clicks and switches tabs very quickly, a plugin could believe the tab is
  87    * visible while Chrome believes it is invisible and the Show() call will
  88    * fail. This will not generally cause user confusion since the user will
  89    * have switched tabs and will not want to see a file chooser from a
  90    * different tab.
  91    *
  92    * @param[in] chooser The file chooser resource.
  93    * @param[in] callback A <code>CompletionCallback</code> to be called after
  94    * the user has closed the file chooser dialog.
  95    *
  96    * @return PP_OK_COMPLETIONPENDING if request to show the dialog was
  97    * successful, another error code from pp_errors.h on failure.
  98    */
  99   [deprecate=0.6]
 100   int32_t Show(
 101       [in] PP_Resource chooser,
 102       [in] PP_CompletionCallback callback);
 103
 104   /**
 105    * After a successful completion callback call from Show, this method may be
 106    * used to query the chosen files.  It should be called in a loop until it
 107    * returns 0.  Their file system type will be PP_FileSystemType_External.  If
 108    * the user chose no files or canceled the dialog, then this method will
 109    * simply return 0 the first time it is called.
 110    *
 111    * @param[in] chooser The file chooser resource.
 112    *
 113    * @return A <code>PP_Resource</code> containing the next file chosen by the
 114    * user, or 0 if there are no more files.
 115    */
 116   [deprecate=0.6]
 117   PP_Resource GetNextChosenFile(
 118       [in] PP_Resource chooser);
 119
 120   /**
 121    * This function displays a previously created file chooser resource as a
 122    * dialog box, prompting the user to choose a file or files. This function
 123    * must be called in response to a user gesture, such as a mouse click or
 124    * touch event. The callback is called with PP_OK on successful completion
 125    * with a file (or files) selected, PP_ERROR_USERCANCEL if the user selected
 126    * no file, or another error code from pp_errors.h on failure.
 127    *
 128    * <b>Subtle note:</b> This function will only work when the tab containing
 129    * the plugin is visible. Show() will fail if the tab is in the background.
 130    * Since it's not normally possible to get input events while invisible, this
 131    * is not normally an issue. But there is a race condition because events are
 132    * processed asynchronously. If the user clicks and switches tabs very
 133    * quickly, a plugin could believe the tab is visible while Chrome believes
 134    * it is invisible and the Show() call will fail. This will not generally
 135    * cause user confusion since the user will have switched tabs and will not
 136    * want to see a file chooser from a different tab.
 137    *
 138    * @param[in] chooser The file chooser resource.
 139    *
 140    * @param[in] output An output array which will receive PP_Resource(s)
 141    * identifying the <code>PPB_FileRef</code> objects that the user selected on
 142    * success.
 143    *
 144    * @param[in] callback A <code>CompletionCallback</code> to be called after
 145    * the user has closed the file chooser dialog.
 146    *
 147    * @return PP_OK_COMPLETIONPENDING if request to show the dialog was
 148    * successful, another error code from pp_errors.h on failure.
 149    */
 150   [version=0.6]
 151   int32_t Show([in] PP_Resource chooser,
 152                [in] PP_ArrayOutput output,
 153                [in] PP_CompletionCallback callback);
 154 };
 155