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 FileSystem;
  21 class CompletionCallback;
  22 template <typename T> class CompletionCallbackWithOutput;
  23
  24 /// The <code>FileRef</code> class represents a "weak pointer" to a file in
  25 /// a file system.
  26 class FileRef : public Resource {
  27  public:
  28   /// Default constructor for creating an is_null() <code>FileRef</code>
  29   /// object.
  30   FileRef() {}
  31
  32   /// A constructor used when you have an existing PP_Resource for a FileRef
  33   /// and which to create a C++ object that takes an additional reference to
  34   /// the resource.
  35   ///
  36   /// @param[in] resource A PP_Resource corresponding to file reference.
  37   explicit FileRef(PP_Resource resource);
  38
  39   /// A constructor used when you have received a PP_Resource as a return
  40   /// value that has already been reference counted.
  41   ///
  42   /// @param[in] resource A PP_Resource corresponding to file reference.
  43   FileRef(PassRef, PP_Resource resource);
  44
  45   /// A constructor that creates a weak pointer to a file in the given file
  46   /// system. File paths are POSIX style.
  47   ///
  48   /// @param[in] file_system A <code>FileSystem</code> corresponding to a file
  49   /// system typ.
  50   /// @param[in] path A path to the file.
  51   FileRef(const FileSystem& file_system, const char* path);
  52
  53   /// The copy constructor for <code>FileRef</code>.
  54   ///
  55   /// @param[in] other A pointer to a <code>FileRef</code>.
  56   FileRef(const FileRef& other);
  57
  58   /// GetFileSystemType() returns the type of the file system.
  59   ///
  60   /// @return A <code>PP_FileSystemType</code> with the file system type if
  61   /// valid or <code>PP_FILESYSTEMTYPE_INVALID</code> if the provided resource
  62   /// is not a valid file reference.
  63   PP_FileSystemType GetFileSystemType() const;
  64
  65   /// GetName() returns the name of the file.
  66   ///
  67   /// @return A <code>Var</code> containing the name of the file.  The value
  68   /// returned by this function does not include any path components (such as
  69   /// the name of the parent directory, for example). It is just the name of the
  70   /// file. Use GetPath() to get the full file path.
  71   Var GetName() const;
  72
  73   /// GetPath() returns the absolute path of the file.
  74   ///
  75   /// @return A <code>Var</code> containing the absolute path of the file.
  76   /// This function fails if the file system type is
  77   /// <code>PP_FileSystemType_External</code>.
  78   Var GetPath() const;
  79
  80   /// GetParent() returns the parent directory of this file.  If
  81   /// <code>file_ref</code> points to the root of the filesystem, then the root
  82   /// is returned.
  83   ///
  84   /// @return A <code>FileRef</code> containing the parent directory of the
  85   /// file. This function fails if the file system type is
  86   /// <code>PP_FileSystemType_External</code>.
  87   FileRef GetParent() const;
  88
  89   /// MakeDirectory() makes a new directory in the file system.  It is not
  90   /// valid to make a directory in the external file system.
  91   /// <strong>Note:</strong> Use MakeDirectoryIncludingAncestors() to create
  92   /// parent directories.
  93   ///
  94   /// @param[in] cc A <code>CompletionCallback</code> to be called upon
  95   /// completion of MakeDirectory().
  96   ///
  97   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
  98   /// Fails if the directory already exists.
  99   int32_t MakeDirectory(const CompletionCallback& cc);
 100
 101   /// MakeDirectoryIncludingAncestors() makes a new directory in the file
 102   /// system as well as any parent directories. It is not valid to make a
 103   /// directory in the external file system.
 104   ///
 105   /// @param[in] cc A <code>CompletionCallback</code> to be called upon
 106   /// completion of MakeDirectoryIncludingAncestors().
 107   ///
 108   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
 109   /// Fails if the directory already exists.
 110   int32_t MakeDirectoryIncludingAncestors(const CompletionCallback& cc);
 111
 112   /// Touch() Updates time stamps for a file.  You must have write access to the
 113   /// file if it exists in the external filesystem.
 114   ///
 115   /// @param[in] last_access_time The last time the file was accessed.
 116   /// @param[in] last_modified_time The last time the file was modified.
 117   /// @param[in] cc A <code>CompletionCallback</code> to be called upon
 118   /// completion of Touch().
 119   ///
 120   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
 121   int32_t Touch(PP_Time last_access_time,
 122                 PP_Time last_modified_time,
 123                 const CompletionCallback& cc);
 124
 125   /// Delete() deletes a file or directory. If <code>file_ref</code> refers to
 126   /// a directory, then the directory must be empty. It is an error to delete a
 127   /// file or directory that is in use.  It is not valid to delete a file in
 128   /// the external file system.
 129   ///
 130   /// @param[in] cc A <code>CompletionCallback</code> to be called upon
 131   /// completion of Delete().
 132   ///
 133   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
 134   int32_t Delete(const CompletionCallback& cc);
 135
 136   /// Rename() renames a file or directory. Argument <code>new_file_ref</code>
 137   /// must refer to files in the same file system as in this object. It is an
 138   /// error to rename a file or directory that is in use.  It is not valid to
 139   /// rename a file in the external file system.
 140   ///
 141   /// @param[in] new_file_ref A <code>FileRef</code> corresponding to a new
 142   /// file reference.
 143   /// @param[in] cc A <code>CompletionCallback</code> to be called upon
 144   /// completion of Rename().
 145   ///
 146   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
 147   int32_t Rename(const FileRef& new_file_ref, const CompletionCallback& cc);
 148
 149   ///
 150   /// Query() queries info about a file or directory. You must have access to
 151   /// read this file or directory if it exists in the external filesystem.
 152   ///
 153   /// @param[in] callback A <code>CompletionCallbackWithOutput</code>
 154   /// to be called upon completion of Query().
 155   ///
 156   /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
 157   int32_t Query(const CompletionCallbackWithOutput<PP_FileInfo>& callback);
 158 };
 159
 160 }  // namespace pp
 161
 162 #endif  // PPAPI_CPP_FILE_REF_H_