ppapi/cpp/dev/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 #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
  15 namespace pp {
  16
  17 class CompletionCallback;
  18 class FileRef;
  19 class InstanceHandle;
  20 class Var;
  21
  22 class 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_