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 13label 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)] 23enum 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 34interface 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 156