Pepper_31_C++_interfaces
file_ref.h
Go to the documentation of this file.
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  /// @param[in] file_system A <code>FileSystem</code> corresponding to a file
50  /// system type.
51  /// @param[in] path A path to the file. Must begin with a '/' character.
52  FileRef(const FileSystem& file_system, const char* path);
53 
54  /// The copy constructor for <code>FileRef</code>.
55  ///
56  /// @param[in] other A pointer to a <code>FileRef</code>.
57  FileRef(const FileRef& other);
58 
59  /// GetFileSystemType() returns the type of the file system.
60  ///
61  /// @return A <code>PP_FileSystemType</code> with the file system type if
62  /// valid or <code>PP_FILESYSTEMTYPE_INVALID</code> if the provided resource
63  /// is not a valid file reference.
64  PP_FileSystemType GetFileSystemType() const;
65 
66  /// GetName() returns the name of the file.
67  ///
68  /// @return A <code>Var</code> containing the name of the file. The value
69  /// returned by this function does not include any path components (such as
70  /// the name of the parent directory, for example). It is just the name of the
71  /// file. Use GetPath() to get the full file path.
72  Var GetName() const;
73 
74  /// GetPath() returns the absolute path of the file.
75  ///
76  /// @return A <code>Var</code> containing the absolute path of the file.
77  /// This function fails if the file system type is
78  /// <code>PP_FileSystemType_External</code>.
79  Var GetPath() const;
80 
81  /// GetParent() returns the parent directory of this file. If
82  /// <code>file_ref</code> points to the root of the filesystem, then the root
83  /// is returned.
84  ///
85  /// @return A <code>FileRef</code> containing the parent directory of the
86  /// file. This function fails if the file system type is
87  /// <code>PP_FileSystemType_External</code>.
88  FileRef GetParent() const;
89 
90  /// MakeDirectory() makes a new directory in the file system. It is not
91  /// valid to make a directory in the external file system.
92  /// <strong>Note:</strong> Use MakeDirectoryIncludingAncestors() to create
93  /// parent directories.
94  ///
95  /// @param[in] cc A <code>CompletionCallback</code> to be called upon
96  /// completion of MakeDirectory().
97  ///
98  /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
99  /// Succeeds if the directory already exists. Fails if ancestor
100  /// directortories do not exist (see MakeDirectoryIncludingAncestors for the
101  /// alternative).
103 
104  /// MakeDirectoryIncludingAncestors() makes a new directory in the file
105  /// system as well as any parent directories. It is not valid to make a
106  /// directory in the external file system.
107  ///
108  /// @param[in] cc A <code>CompletionCallback</code> to be called upon
109  /// completion of MakeDirectoryIncludingAncestors().
110  ///
111  /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
112  /// Succeeds if the directory already exists.
114 
115  /// Touch() Updates time stamps for a file. You must have write access to the
116  /// file if it exists in the external filesystem.
117  ///
118  /// @param[in] last_access_time The last time the file was accessed.
119  /// @param[in] last_modified_time The last time the file was modified.
120  /// @param[in] cc A <code>CompletionCallback</code> to be called upon
121  /// completion of Touch().
122  ///
123  /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
124  int32_t Touch(PP_Time last_access_time,
125  PP_Time last_modified_time,
126  const CompletionCallback& cc);
127 
128  /// Delete() deletes a file or directory. If <code>file_ref</code> refers to
129  /// a directory, then the directory must be empty. It is an error to delete a
130  /// file or directory that is in use. It is not valid to delete a file in
131  /// the external file system.
132  ///
133  /// @param[in] cc A <code>CompletionCallback</code> to be called upon
134  /// completion of Delete().
135  ///
136  /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
137  int32_t Delete(const CompletionCallback& cc);
138 
139  /// Rename() renames a file or directory. Argument <code>new_file_ref</code>
140  /// must refer to files in the same file system as in this object. It is an
141  /// error to rename a file or directory that is in use. It is not valid to
142  /// rename a file in the external file system.
143  ///
144  /// @param[in] new_file_ref A <code>FileRef</code> corresponding to a new
145  /// file reference.
146  /// @param[in] cc A <code>CompletionCallback</code> to be called upon
147  /// completion of Rename().
148  ///
149  /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
150  int32_t Rename(const FileRef& new_file_ref, const CompletionCallback& cc);
151 
152  /// Query() queries info about a file or directory. You must have access to
153  /// read this file or directory if it exists in the external filesystem.
154  ///
155  /// @param[in] callback A <code>CompletionCallbackWithOutput</code>
156  /// to be called upon completion of Query().
157  ///
158  /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
160 
161  /// ReadDirectoryEntries() Reads all entries in the directory.
162  ///
163  /// @param[in] cc A <code>CompletionCallbackWithOutput</code> to be called
164  /// upon completion of ReadDirectoryEntries(). On success, the
165  /// directory entries will be passed to the given function.
166  ///
167  /// Normally you would use a CompletionCallbackFactory to allow callbacks to
168  /// be bound to your class. See completion_callback_factory.h for more
169  /// discussion on how to use this. Your callback will generally look like:
170  ///
171  /// @code
172  /// void OnReadDirectoryEntries(
173  /// int32_t result,
174  /// const std::vector<DirectoryEntry>& entries) {
175  /// if (result == PP_OK)
176  /// // use entries...
177  /// }
178  /// @endcode
179  ///
180  /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
182  const CompletionCallbackWithOutput< std::vector<DirectoryEntry> >&
183  callback);
184 };
185 
186 } // namespace pp
187 
188 #endif // PPAPI_CPP_FILE_REF_H_
PP_FileSystemType GetFileSystemType() const
int32_t Delete(const CompletionCallback &cc)
FileRef GetParent() const
int32_t Touch(PP_Time last_access_time, PP_Time last_modified_time, const CompletionCallback &cc)
int32_t ReadDirectoryEntries(const CompletionCallbackWithOutput< std::vector< DirectoryEntry > > &callback)
PassRef
Definition: pass_ref.h:17
Var GetPath() const
Var GetName() const
int32_t MakeDirectory(const CompletionCallback &cc)
int32_t Rename(const FileRef &new_file_ref, const CompletionCallback &cc)
int32_t Query(const CompletionCallbackWithOutput< PP_FileInfo > &callback)
A generic type used for passing data types between the module and the page.
Definition: var.h:20
int32_t MakeDirectoryIncludingAncestors(const CompletionCallback &cc)
A reference counted module resource.
Definition: resource.h:18