ppapi/cpp/file_ref.h

   1 // Copyright (c) 2011 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_FILE_REF_H_
   6 #define PPAPI_CPP_FILE_REF_H_
   7
   8 #include "ppapi/c/pp_file_info.h"
   9 #include "ppapi/c/pp_stdint.h"
  10 #include "ppapi/c/ppb_file_ref.h"
  11 #include "ppapi/cpp/resource.h"
  12 #include "ppapi/cpp/var.h"
  13
  14 /// @file
  15 /// This file defines the API to create a file reference or "weak pointer" to a
  16 /// file in a file system.
  17
  18 namespace pp {
  19
  20 class DirectoryEntry;
  21 class FileSystem;
  22 class CompletionCallback;
  23 template <typename T> class CompletionCallbackWithOutput;
  24
  25 /// The <code>FileRef</code> class represents a "weak pointer" to a file in
  26 /// a file system.
  27 class FileRef : public Resource {
  28  public:
  29   /// Default constructor for creating an is_null() <code>FileRef</code>
  30   /// object.
  31   FileRef() {}
  32
  33   /// A constructor used when you have an existing PP_Resource for a FileRef
  34   /// and which to create a C++ object that takes an additional reference to
  35   /// the resource.
  36   ///
  37   /// @param[in] resource A PP_Resource corresponding to file reference.
  38   explicit FileRef(PP_Resource resource);
  39
  40   /// A constructor used when you have received a PP_Resource as a return
  41   /// value that has already been reference counted.
  42   ///
  43   /// @param[in] resource A PP_Resource corresponding to file reference.
  44   FileRef(PassRef, PP_Resource resource);
  45
  46   /// A constructor that creates a weak pointer to a file in the given file
  47   /// system. File paths are POSIX style.
  48   ///
  49   /// If the <code>path</code> is malformed, the resulting <code>FileRef</code>
  50   /// will have a null <code>PP_Resource</code>.
  51   ///
  52   /// @param[in] file_system A <code>FileSystem</code> corresponding to a file
  53   /// system type.
  54   /// @param[in] path A path to the file. Must begin with a '/' character.
  55   FileRef(const FileSystem& file_system, const char* path);
  56
  57   /// The copy constructor for <code>FileRef</code>.
  58   ///
  59   /// @param[in] other A pointer to a <code>FileRef</code>.
  60   FileRef(const FileRef& other);
  61
  62   /// GetFileSystemType() returns the type of the file system.
  63   ///
  64   /// @return A <code>PP_FileSystemType</code> with the file system type if
  65   /// valid or <code>PP_FILESYSTEMTYPE_INVALID</code> if the provided resource
  66   /// is not a valid file reference.
  67   PP_FileSystemType GetFileSystemType() const;
  68
  69   /// GetName() returns the name of the file.
  70   ///
  71   /// @return A <code>Var</code> containing the name of the file.  The value
  72   /// returned by this function does not include any path components (such as
  73   /// the name of the parent directory, for example). It is just the name of the
  74   /// file. Use GetPath() to get the full file path.
  75   Var GetName() const;
  76
  77   /// GetPath() returns the absolute path of the file.
  78   ///
  79   /// @return A <code>Var</code> containing the absolute path of the file.
  80   /// This function fails if the file system type is
  81   /// <code>PP_FileSystemType_External</code>.
  82   Var GetPath() const;
  83
  84   /// GetParent() returns the parent directory of this file.  If
  85   /// <code>file_ref</code> points to the root of the filesystem, then the root
  86   /// is returned.
  87   ///
  88   /// @return A <code>FileRef</code> containing the parent directory of the
  89   /// file. This function fails if the file system type is
  90   /// <code>PP_FileSystemType_External</code>.
  91   FileRef GetParent() const;
  92
  93   /// MakeDirectory() makes a new directory in the file system according to the
  94   /// given <code>make_directory_flags</code>, which is a bit-mask of the
  95   /// <code>PP_MakeDirectoryFlags</code> values.  It is not valid to make a
  96   /// directory in the external file system.
  97   ///
  98   /// @param[in] make_directory_flags A bit-mask of the
  99   /// <code>PP_MakeDirectoryFlags</code> values.
 100   /// See <code>ppb_file_ref.h</code> for more details.
 101   /// @param[in] cc A <code>CompletionCallback</code> to be called upon
 102   /// completion of MakeDirectory().
 103   ///
 104   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
 105   int32_t MakeDirectory(int32_t make_directory_flags,
 106                         const CompletionCallback& cc);
 107
 108   /// Touch() Updates time stamps for a file.  You must have write access to the
 109   /// file if it exists in the external filesystem.
 110   ///
 111   /// @param[in] last_access_time The last time the file was accessed.
 112   /// @param[in] last_modified_time The last time the file was modified.
 113   /// @param[in] cc A <code>CompletionCallback</code> to be called upon
 114   /// completion of Touch().
 115   ///
 116   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
 117   int32_t Touch(PP_Time last_access_time,
 118                 PP_Time last_modified_time,
 119                 const CompletionCallback& cc);
 120
 121   /// Delete() deletes a file or directory. If <code>file_ref</code> refers to
 122   /// a directory, then the directory must be empty. It is an error to delete a
 123   /// file or directory that is in use.  It is not valid to delete a file in
 124   /// the external file system.
 125   ///
 126   /// @param[in] cc A <code>CompletionCallback</code> to be called upon
 127   /// completion of Delete().
 128   ///
 129   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
 130   int32_t Delete(const CompletionCallback& cc);
 131
 132   /// Rename() renames a file or directory. Argument <code>new_file_ref</code>
 133   /// must refer to files in the same file system as in this object. It is an
 134   /// error to rename a file or directory that is in use.  It is not valid to
 135   /// rename a file in the external file system.
 136   ///
 137   /// @param[in] new_file_ref A <code>FileRef</code> corresponding to a new
 138   /// file reference.
 139   /// @param[in] cc A <code>CompletionCallback</code> to be called upon
 140   /// completion of Rename().
 141   ///
 142   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
 143   int32_t Rename(const FileRef& new_file_ref, const CompletionCallback& cc);
 144
 145   /// Query() queries info about a file or directory. You must have access to
 146   /// read this file or directory if it exists in the external filesystem.
 147   ///
 148   /// @param[in] callback A <code>CompletionCallbackWithOutput</code>
 149   /// to be called upon completion of Query().
 150   ///
 151   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
 152   int32_t Query(const CompletionCallbackWithOutput<PP_FileInfo>& callback);
 153
 154   /// ReadDirectoryEntries() Reads all entries in the directory.
 155   ///
 156   /// @param[in] cc A <code>CompletionCallbackWithOutput</code> to be called
 157   /// upon completion of ReadDirectoryEntries(). On success, the
 158   /// directory entries will be passed to the given function.
 159   ///
 160   /// Normally you would use a CompletionCallbackFactory to allow callbacks to
 161   /// be bound to your class. See completion_callback_factory.h for more
 162   /// discussion on how to use this. Your callback will generally look like:
 163   ///
 164   /// @code
 165   ///   void OnReadDirectoryEntries(
 166   ///       int32_t result,
 167   ///       const std::vector<DirectoryEntry>& entries) {
 168   ///     if (result == PP_OK)
 169   ///       // use entries...
 170   ///   }
 171   /// @endcode
 172   ///
 173   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
 174   int32_t ReadDirectoryEntries(
 175       const CompletionCallbackWithOutput< std::vector<DirectoryEntry> >&
 176           callback);
 177 };
 178
 179 }  // namespace pp
 180
 181 #endif  // PPAPI_CPP_FILE_REF_H_