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_ 182
