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. FileRef()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. It is not 94 /// valid to make a directory in the external file system. 95 /// <strong>Note:</strong> Use MakeDirectoryIncludingAncestors() to create 96 /// parent directories. 97 /// 98 /// @param[in] cc A <code>CompletionCallback</code> to be called upon 99 /// completion of MakeDirectory(). 100 /// 101 /// @return An int32_t containing an error code from <code>pp_errors.h</code>. 102 /// Succeeds if the directory already exists. Fails if ancestor 103 /// directortories do not exist (see MakeDirectoryIncludingAncestors for the 104 /// alternative). 105 int32_t MakeDirectory(const CompletionCallback& cc); 106 107 /// MakeDirectoryIncludingAncestors() makes a new directory in the file 108 /// system as well as any parent directories. It is not valid to make a 109 /// directory in the external file system. 110 /// 111 /// @param[in] cc A <code>CompletionCallback</code> to be called upon 112 /// completion of MakeDirectoryIncludingAncestors(). 113 /// 114 /// @return An int32_t containing an error code from <code>pp_errors.h</code>. 115 /// Succeeds if the directory already exists. 116 int32_t MakeDirectoryIncludingAncestors(const CompletionCallback& cc); 117 118 /// Touch() Updates time stamps for a file. You must have write access to the 119 /// file if it exists in the external filesystem. 120 /// 121 /// @param[in] last_access_time The last time the file was accessed. 122 /// @param[in] last_modified_time The last time the file was modified. 123 /// @param[in] cc A <code>CompletionCallback</code> to be called upon 124 /// completion of Touch(). 125 /// 126 /// @return An int32_t containing an error code from <code>pp_errors.h</code>. 127 int32_t Touch(PP_Time last_access_time, 128 PP_Time last_modified_time, 129 const CompletionCallback& cc); 130 131 /// Delete() deletes a file or directory. If <code>file_ref</code> refers to 132 /// a directory, then the directory must be empty. It is an error to delete a 133 /// file or directory that is in use. It is not valid to delete a file in 134 /// the external file system. 135 /// 136 /// @param[in] cc A <code>CompletionCallback</code> to be called upon 137 /// completion of Delete(). 138 /// 139 /// @return An int32_t containing an error code from <code>pp_errors.h</code>. 140 int32_t Delete(const CompletionCallback& cc); 141 142 /// Rename() renames a file or directory. Argument <code>new_file_ref</code> 143 /// must refer to files in the same file system as in this object. It is an 144 /// error to rename a file or directory that is in use. It is not valid to 145 /// rename a file in the external file system. 146 /// 147 /// @param[in] new_file_ref A <code>FileRef</code> corresponding to a new 148 /// file reference. 149 /// @param[in] cc A <code>CompletionCallback</code> to be called upon 150 /// completion of Rename(). 151 /// 152 /// @return An int32_t containing an error code from <code>pp_errors.h</code>. 153 int32_t Rename(const FileRef& new_file_ref, const CompletionCallback& cc); 154 155 /// Query() queries info about a file or directory. You must have access to 156 /// read this file or directory if it exists in the external filesystem. 157 /// 158 /// @param[in] callback A <code>CompletionCallbackWithOutput</code> 159 /// to be called upon completion of Query(). 160 /// 161 /// @return An int32_t containing an error code from <code>pp_errors.h</code>. 162 int32_t Query(const CompletionCallbackWithOutput<PP_FileInfo>& callback); 163 164 /// ReadDirectoryEntries() Reads all entries in the directory. 165 /// 166 /// @param[in] cc A <code>CompletionCallbackWithOutput</code> to be called 167 /// upon completion of ReadDirectoryEntries(). On success, the 168 /// directory entries will be passed to the given function. 169 /// 170 /// Normally you would use a CompletionCallbackFactory to allow callbacks to 171 /// be bound to your class. See completion_callback_factory.h for more 172 /// discussion on how to use this. Your callback will generally look like: 173 /// 174 /// @code 175 /// void OnReadDirectoryEntries( 176 /// int32_t result, 177 /// const std::vector<DirectoryEntry>& entries) { 178 /// if (result == PP_OK) 179 /// // use entries... 180 /// } 181 /// @endcode 182 /// 183 /// @return An int32_t containing an error code from <code>pp_errors.h</code>. 184 int32_t ReadDirectoryEntries( 185 const CompletionCallbackWithOutput< std::vector<DirectoryEntry> >& 186 callback); 187 }; 188 189 } // namespace pp 190 191 #endif // PPAPI_CPP_FILE_REF_H_ 192