src/ppapi/c/dev/ppb_file_chooser_dev.h

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