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#ifndef PPAPI_CPP_DEV_FILE_CHOOSER_DEV_H_
6#define PPAPI_CPP_DEV_FILE_CHOOSER_DEV_H_
7
8#include <vector>
9
10#include "ppapi/c/dev/ppb_file_chooser_dev.h"
11#include "ppapi/cpp/completion_callback.h"
12#include "ppapi/cpp/file_ref.h"
13#include "ppapi/cpp/resource.h"
14
15namespace pp {
16
17class CompletionCallback;
18class FileRef;
19class InstanceHandle;
20class Var;
21
22class FileChooser_Dev : public Resource {
23 public:
24  /// Creates an is_null() FileChooser object.
25  FileChooser_Dev() {}
26
27  /// This function creates a file chooser dialog resource.  The chooser is
28  /// associated with a particular instance, so that it may be positioned on the
29  /// screen relative to the tab containing the instance.  Returns 0 if passed
30  /// an invalid instance.
31  ///
32  /// @param mode A PPB_FileChooser_Dev instance can be used to select a single
33  /// file (PP_FILECHOOSERMODE_OPEN) or multiple files
34  /// (PP_FILECHOOSERMODE_OPENMULTIPLE). Unlike the HTML5 <input type="file">
35  /// tag, a PPB_FileChooser_Dev instance cannot be used to select a directory.
36  /// In order to get the list of files in a directory, the
37  /// PPB_FileRef::ReadDirectoryEntries interface must be used.
38  ///
39  /// @param accept_types A comma-separated list of MIME types and file
40  /// extensions such as "audio/ *,text/plain,.html" (note there should be
41  /// no space between the '/' and the '*', but one is added to avoid confusing
42  /// C++ comments). The dialog may restrict selectable files to the specified
43  /// MIME types and file extensions. If a string in the comma-separated list
44  /// begins with a period (.) then the string is interpreted as a file
45  /// extension, otherwise it is interpreted as a MIME-type. An empty string or
46  /// an undefined var may be given to indicate that all types should be
47  /// accepted.
48  FileChooser_Dev(const InstanceHandle& instance,
49                  PP_FileChooserMode_Dev mode,
50                  const Var& accept_types);
51
52  FileChooser_Dev(const FileChooser_Dev& other);
53
54  /// This function displays a previously created file chooser resource as a
55  /// dialog box, prompting the user to choose a file or files. This function
56  /// must be called in response to a user gesture, such as a mouse click or
57  /// touch event. The callback is called with PP_OK on successful completion
58  /// with a file (or files) selected, PP_ERROR_USERCANCEL if the user selected
59  /// no file, or another error code from pp_errors.h on failure.
60  ///
61  /// @param callback The completion callback that will be executed. On success,
62  /// the selected files will be passed to the given function.
63  ///
64  /// Normally you would use a CompletionCallbackFactory to allow callbacks to
65  /// be bound to your class. See completion_callback_factory.h for more
66  /// discussion on how to use this. Your callback will generally look like:
67  ///
68  /// @code
69  ///   void OnFilesSelected(int32_t result,
70  ///                        const std::vector<pp::FileRef>& files) {
71  ///     if (result == PP_OK)
72  ///       // use files...
73  ///   }
74  /// @endcode
75  ///
76  /// @return PP_OK_COMPLETIONPENDING if request to show the dialog was
77  /// successful, another error code from pp_errors.h on failure.
78  virtual int32_t Show(
79      const CompletionCallbackWithOutput< std::vector<FileRef> >& callback);
80
81 protected:
82  // Heap-allocated data passed to the CallbackConverter for backwards compat.
83  struct ChooseCallbackData0_5 {
84    PP_Resource file_chooser;
85    PP_ArrayOutput output;
86    PP_CompletionCallback original_callback;
87  };
88
89  // Provide backwards-compatibility for older versions. Converts the old-style
90  // 0.5 "iterator" interface to the new-style 0.6 "array output" interface that
91  // the caller is expecting.
92  //
93  // This takes a heap-allocated ChooseCallbackData0_5 struct passed as the
94  // user data and deletes it when the call completes.
95  static void CallbackConverter(void* user_data, int32_t result);
96};
97
98}  // namespace pp
99
100#endif  // PPAPI_CPP_DEV_FILE_CHOOSER_DEV_H_
101