15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Copyright (c) 2011 The Chromium Authors. All rights reserved. 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Use of this source code is governed by a BSD-style license that can be 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// found in the LICENSE file. 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifndef PPAPI_CPP_FILE_REF_H_ 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PPAPI_CPP_FILE_REF_H_ 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 8c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)#include "ppapi/c/pp_file_info.h" 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/c/pp_stdint.h" 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/c/ppb_file_ref.h" 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/cpp/resource.h" 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/cpp/var.h" 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// @file 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// This file defines the API to create a file reference or "weak pointer" to a 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// file in a file system. 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace pp { 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 20c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)class DirectoryEntry; 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class FileSystem; 22c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)class CompletionCallback; 23c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)template <typename T> class CompletionCallbackWithOutput; 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// The <code>FileRef</code> class represents a "weak pointer" to a file in 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// a file system. 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class FileRef : public Resource { 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public: 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// Default constructor for creating an is_null() <code>FileRef</code> 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// object. 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) FileRef() {} 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// A constructor used when you have an existing PP_Resource for a FileRef 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// and which to create a C++ object that takes an additional reference to 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// the resource. 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] resource A PP_Resource corresponding to file reference. 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) explicit FileRef(PP_Resource resource); 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// A constructor used when you have received a PP_Resource as a return 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// value that has already been reference counted. 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] resource A PP_Resource corresponding to file reference. 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) FileRef(PassRef, PP_Resource resource); 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// A constructor that creates a weak pointer to a file in the given file 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// system. File paths are POSIX style. 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 491e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) /// If the <code>path</code> is malformed, the resulting <code>FileRef</code> 501e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) /// will have a null <code>PP_Resource</code>. 511e9bf3e0803691d0a228da41fc608347b6db4340Torne (Richard Coles) /// 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] file_system A <code>FileSystem</code> corresponding to a file 53b2df76ea8fec9e32f6f3718986dba0d95315b29cTorne (Richard Coles) /// system type. 543551c9c881056c480085172ff9840cab31610854Torne (Richard Coles) /// @param[in] path A path to the file. Must begin with a '/' character. 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) FileRef(const FileSystem& file_system, const char* path); 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// The copy constructor for <code>FileRef</code>. 585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] other A pointer to a <code>FileRef</code>. 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) FileRef(const FileRef& other); 615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// GetFileSystemType() returns the type of the file system. 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @return A <code>PP_FileSystemType</code> with the file system type if 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// valid or <code>PP_FILESYSTEMTYPE_INVALID</code> if the provided resource 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// is not a valid file reference. 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PP_FileSystemType GetFileSystemType() const; 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// GetName() returns the name of the file. 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @return A <code>Var</code> containing the name of the file. The value 725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// returned by this function does not include any path components (such as 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// the name of the parent directory, for example). It is just the name of the 745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// file. Use GetPath() to get the full file path. 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Var GetName() const; 765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// GetPath() returns the absolute path of the file. 785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @return A <code>Var</code> containing the absolute path of the file. 805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// This function fails if the file system type is 815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>PP_FileSystemType_External</code>. 825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Var GetPath() const; 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// GetParent() returns the parent directory of this file. If 855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>file_ref</code> points to the root of the filesystem, then the root 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// is returned. 875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @return A <code>FileRef</code> containing the parent directory of the 895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// file. This function fails if the file system type is 905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>PP_FileSystemType_External</code>. 915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) FileRef GetParent() const; 925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 935d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) /// MakeDirectory() makes a new directory in the file system according to the 945d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) /// given <code>make_directory_flags</code>, which is a bit-mask of the 955d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) /// <code>PP_MakeDirectoryFlags</code> values. It is not valid to make a 965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// directory in the external file system. 975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 985d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) /// @param[in] make_directory_flags A bit-mask of the 995d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) /// <code>PP_MakeDirectoryFlags</code> values. 1005d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) /// See <code>ppb_file_ref.h</code> for more details. 1015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] cc A <code>CompletionCallback</code> to be called upon 1025d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) /// completion of MakeDirectory(). 1035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 1045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @return An int32_t containing an error code from <code>pp_errors.h</code>. 1055d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) int32_t MakeDirectory(int32_t make_directory_flags, 1065d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) const CompletionCallback& cc); 1075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// Touch() Updates time stamps for a file. You must have write access to the 1095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// file if it exists in the external filesystem. 1105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 1115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] last_access_time The last time the file was accessed. 1125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] last_modified_time The last time the file was modified. 1135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] cc A <code>CompletionCallback</code> to be called upon 1145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// completion of Touch(). 1155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 1165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @return An int32_t containing an error code from <code>pp_errors.h</code>. 1175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int32_t Touch(PP_Time last_access_time, 1185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PP_Time last_modified_time, 1195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const CompletionCallback& cc); 1205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// Delete() deletes a file or directory. If <code>file_ref</code> refers to 1225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// a directory, then the directory must be empty. It is an error to delete a 1235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// file or directory that is in use. It is not valid to delete a file in 1245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// the external file system. 1255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 1265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] cc A <code>CompletionCallback</code> to be called upon 1275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// completion of Delete(). 1285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 1295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @return An int32_t containing an error code from <code>pp_errors.h</code>. 1305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int32_t Delete(const CompletionCallback& cc); 1315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// Rename() renames a file or directory. Argument <code>new_file_ref</code> 1335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// must refer to files in the same file system as in this object. It is an 1345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// error to rename a file or directory that is in use. It is not valid to 1355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// rename a file in the external file system. 1365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 1375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] new_file_ref A <code>FileRef</code> corresponding to a new 1385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// file reference. 1395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] cc A <code>CompletionCallback</code> to be called upon 1405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// completion of Rename(). 1415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 1425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @return An int32_t containing an error code from <code>pp_errors.h</code>. 1435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int32_t Rename(const FileRef& new_file_ref, const CompletionCallback& cc); 144c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 145c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// Query() queries info about a file or directory. You must have access to 146c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// read this file or directory if it exists in the external filesystem. 147c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// 148c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// @param[in] callback A <code>CompletionCallbackWithOutput</code> 149c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// to be called upon completion of Query(). 150c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// 151c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// @return An int32_t containing an error code from <code>pp_errors.h</code>. 152c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) int32_t Query(const CompletionCallbackWithOutput<PP_FileInfo>& callback); 153c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 154c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// ReadDirectoryEntries() Reads all entries in the directory. 155c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// 156c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// @param[in] cc A <code>CompletionCallbackWithOutput</code> to be called 157c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// upon completion of ReadDirectoryEntries(). On success, the 158c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// directory entries will be passed to the given function. 159c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// 160c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// Normally you would use a CompletionCallbackFactory to allow callbacks to 161c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// be bound to your class. See completion_callback_factory.h for more 162c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// discussion on how to use this. Your callback will generally look like: 163c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// 164c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// @code 165c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// void OnReadDirectoryEntries( 166c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// int32_t result, 167c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// const std::vector<DirectoryEntry>& entries) { 168c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// if (result == PP_OK) 169c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// // use entries... 170c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// } 171c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// @endcode 172c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// 173c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// @return An int32_t containing an error code from <code>pp_errors.h</code>. 174c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) int32_t ReadDirectoryEntries( 175c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) const CompletionCallbackWithOutput< std::vector<DirectoryEntry> >& 176c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) callback); 1775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 1785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} // namespace pp 1805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif // PPAPI_CPP_FILE_REF_H_ 182