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// File contains the fileBrowserHandlerInternal.selectFile extension function.
6// The function prompts user to select a file path to be used by the caller. It
7// will fail if it isn't invoked by a user gesture (e.g. a mouse click or a
8// keyboard key press).
9// Note that the target file is never actually created by this function, even
10// if the selected path doesn't exist.
11
12#ifndef CHROME_BROWSER_CHROMEOS_EXTENSIONS_FILE_MANAGER_FILE_BROWSER_HANDLER_API_H_
13#define CHROME_BROWSER_CHROMEOS_EXTENSIONS_FILE_MANAGER_FILE_BROWSER_HANDLER_API_H_
14
15#include <string>
16#include <vector>
17
18#include "base/files/file_path.h"
19#include "chrome/browser/extensions/chrome_extension_function.h"
20
21class Browser;
22class FileBrowserHandlerInternalSelectFileFunction;
23
24namespace file_manager {
25
26namespace util {
27struct EntryDefinition;
28struct FileDefinition;
29}
30
31// Interface that is used by FileBrowserHandlerInternalSelectFileFunction to
32// select the file path that should be reported back to the extension function
33// caller.  Nobody will take the ownership of the interface implementation, so
34// it should delete itself once it's done.
35class FileSelector {
36 public:
37  virtual ~FileSelector() {}
38
39  // Starts the file selection. It should prompt user to select a file path.
40  // Once the selection is made it should asynchronously call
41  // |function_->OnFilePathSelected| with the selection information.
42  // User should be initially suggested to select file named |suggested_name|.
43  // |allowed_extensions| specifies the file extensions allowed to be shown,
44  // and selected. Extensions should not include '.'. This spec comes from
45  // ui::SelectFileDialog() which takes extensions without '.'.
46  //
47  // Selection UI should be displayed using |browser|. |browser| should outlive
48  // the interface implementation.
49  // |function| if the extension function that called the method and needs to
50  // be notified of user action. The interface implementation should keep a
51  // reference to the function until it is notified (extension function
52  // implementations are ref counted).
53  // |SelectFile| will be called at most once by a single extension function.
54  // The interface implementation should delete itself after the extension
55  // function is notified of file selection result.
56  virtual void SelectFile(
57      const base::FilePath& suggested_name,
58      const std::vector<std::string>& allowed_extensions,
59      Browser* browser,
60      FileBrowserHandlerInternalSelectFileFunction* function) = 0;
61};
62
63// Interface that is used by FileBrowserHandlerInternalSelectFileFunction to
64// create a FileSelector it can use to select a file path.
65class FileSelectorFactory {
66 public:
67  virtual ~FileSelectorFactory() {}
68
69  // Creates a FileSelector instance for the
70  // FileBrowserHandlerInternalSelectFileFunction.
71  virtual FileSelector* CreateFileSelector() const = 0;
72};
73
74}  // namespace file_manager
75
76
77// Note that this class is not in 'file_manager' class to be consistent with
78// all other extension functions registered in
79// chrome/common/extensions/api/generated_api.cc being in the global namespace.
80//
81// The fileBrowserHandlerInternal.selectFile extension function implementation.
82// See the file description for more info.
83class FileBrowserHandlerInternalSelectFileFunction
84    : public ChromeAsyncExtensionFunction {
85 public:
86  // Default constructor used in production code.
87  // It will create its own FileSelectorFactory implementation, and set the
88  // value of |user_gesture_check_enabled| to true.
89  FileBrowserHandlerInternalSelectFileFunction();
90
91  // This constructor should be used only in tests to inject test file selector
92  // factory and to allow extension function to run even if it hasn't been
93  // invoked by user gesture.
94  // Created object will take the ownership of the |file_selector_factory|.
95  FileBrowserHandlerInternalSelectFileFunction(
96      file_manager::FileSelectorFactory* file_selector_factory,
97      bool enable_user_gesture_check);
98
99  // Called by FileSelector implementation when the user selects the file's
100  // file path. File access permissions for the selected file are granted and
101  // caller is notified of the selection result after this method is called.
102  // |success| Whether the path was selected.
103  // |full_path| The selected file path if one was selected. It is ignored if
104  // the selection did not succeed.
105  void OnFilePathSelected(bool success, const base::FilePath& full_path);
106
107 protected:
108  // The class is ref counted, so destructor should not be public.
109  virtual ~FileBrowserHandlerInternalSelectFileFunction();
110
111  // AsyncExtensionFunction implementation.
112  // Runs the extension function implementation.
113  virtual bool RunAsync() OVERRIDE;
114
115 private:
116  // Respond to the API with selected entry definition.
117  void RespondEntryDefinition(
118      const file_manager::util::EntryDefinition& entry_definition);
119
120  // Creates dictionary value that will be used to as the extension function's
121  // callback argument and ends extension function execution by calling
122  // |SendResponse(true)|.
123  // The |results_| value will be set to dictionary containing two properties:
124  // * boolean 'success', which will be equal to |success|.
125  // * object 'entry', which will be set only when |success| is true, and the
126  //   conversion to |entry_definition| was successful. In such case, it will
127  //   contain information needed to create a FileEntry object for the selected
128  //   file.
129  void Respond(const file_manager::util::EntryDefinition& entry_definition,
130               bool success);
131
132  // Factory used to create FileSelector to be used for prompting user to select
133  // file.
134  scoped_ptr<file_manager::FileSelectorFactory> file_selector_factory_;
135  // Whether user gesture check is disabled. This should be true only in tests.
136  bool user_gesture_check_enabled_;
137
138  // List of permissions and paths that have to be granted for the selected
139  // files.
140  std::vector<std::pair<base::FilePath, int> > permissions_to_grant_;
141
142  DECLARE_EXTENSION_FUNCTION("fileBrowserHandlerInternal.selectFile",
143                             FILEBROWSERHANDLERINTERNAL_SELECTFILE)
144};
145
146#endif  // CHROME_BROWSER_CHROMEOS_EXTENSIONS_FILE_MANAGER_FILE_BROWSER_HANDLER_API_H_
147