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 */
38typedef 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;
48PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_FileChooserMode_Dev, 4);
49/**
50 * @}
51 */
52
53/**
54 * @addtogroup Interfaces
55 * @{
56 */
57struct 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
127typedef struct PPB_FileChooser_Dev_0_6 PPB_FileChooser_Dev;
128
129struct 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
143