1/* Copyright (c) 2012 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
6/* From ppb_file_ref.idl modified Wed Jan 29 20:50:29 2014. */
7
8#ifndef PPAPI_C_PPB_FILE_REF_H_
9#define PPAPI_C_PPB_FILE_REF_H_
10
11#include "ppapi/c/pp_array_output.h"
12#include "ppapi/c/pp_bool.h"
13#include "ppapi/c/pp_completion_callback.h"
14#include "ppapi/c/pp_file_info.h"
15#include "ppapi/c/pp_macros.h"
16#include "ppapi/c/pp_resource.h"
17#include "ppapi/c/pp_stdint.h"
18#include "ppapi/c/pp_time.h"
19#include "ppapi/c/pp_var.h"
20
21#define PPB_FILEREF_INTERFACE_1_0 "PPB_FileRef;1.0"
22#define PPB_FILEREF_INTERFACE_1_1 "PPB_FileRef;1.1"
23#define PPB_FILEREF_INTERFACE_1_2 "PPB_FileRef;1.2"
24#define PPB_FILEREF_INTERFACE PPB_FILEREF_INTERFACE_1_2
25
26/**
27 * @file
28 * This file defines the API to create a file reference or "weak pointer" to a
29 * file in a file system.
30 */
31
32
33/**
34 * @addtogroup Enums
35 * @{
36 */
37/**
38 * The <code>PP_MakeDirectoryFlags</code> enum contains flags used to control
39 * behavior of <code>PPB_FileRef.MakeDirectory()</code>.
40 */
41typedef enum {
42  PP_MAKEDIRECTORYFLAG_NONE = 0 << 0,
43  /** Requests that ancestor directories are created if they do not exist. */
44  PP_MAKEDIRECTORYFLAG_WITH_ANCESTORS = 1 << 0,
45  /**
46   * Requests that the PPB_FileRef.MakeDirectory() call fails if the directory
47   * already exists.
48   */
49  PP_MAKEDIRECTORYFLAG_EXCLUSIVE = 1 << 1
50} PP_MakeDirectoryFlags;
51/**
52 * @}
53 */
54
55/**
56 * @addtogroup Interfaces
57 * @{
58 */
59/**
60 * The <code>PPB_FileRef</code> struct represents a "weak pointer" to a file in
61 * a file system.  This struct contains a <code>PP_FileSystemType</code>
62 * identifier and a file path string.
63 */
64struct PPB_FileRef_1_2 {
65  /**
66   * Create() creates a weak pointer to a file in the given file system. File
67   * paths are POSIX style.
68   *
69   * @param[in] resource A <code>PP_Resource</code> corresponding to a file
70   * system.
71   * @param[in] path A path to the file. Must begin with a '/' character.
72   *
73   * @return A <code>PP_Resource</code> corresponding to a file reference if
74   * successful or 0 if the path is malformed.
75   */
76  PP_Resource (*Create)(PP_Resource file_system, const char* path);
77  /**
78   * IsFileRef() determines if the provided resource is a file reference.
79   *
80   * @param[in] resource A <code>PP_Resource</code> corresponding to a file
81   * reference.
82   *
83   * @return <code>PP_TRUE</code> if the resource is a
84   * <code>PPB_FileRef</code>, <code>PP_FALSE</code> if the resource is
85   * invalid or some type other than <code>PPB_FileRef</code>.
86   */
87  PP_Bool (*IsFileRef)(PP_Resource resource);
88  /**
89   * GetFileSystemType() returns the type of the file system.
90   *
91   * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
92   * reference.
93   *
94   * @return A <code>PP_FileSystemType</code> with the file system type if
95   * valid or <code>PP_FILESYSTEMTYPE_INVALID</code> if the provided resource
96   * is not a valid file reference.
97   */
98  PP_FileSystemType (*GetFileSystemType)(PP_Resource file_ref);
99  /**
100   * GetName() returns the name of the file.
101   *
102   * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
103   * reference.
104   *
105   * @return A <code>PP_Var</code> containing the name of the file.  The value
106   * returned by this function does not include any path components (such as
107   * the name of the parent directory, for example). It is just the name of the
108   * file. Use GetPath() to get the full file path.
109   */
110  struct PP_Var (*GetName)(PP_Resource file_ref);
111  /**
112   * GetPath() returns the absolute path of the file.
113   *
114   * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
115   * reference.
116   *
117   * @return A <code>PP_Var</code> containing the absolute path of the file.
118   * This function fails if the file system type is
119   * <code>PP_FileSystemType_External</code>.
120   */
121  struct PP_Var (*GetPath)(PP_Resource file_ref);
122  /**
123   * GetParent() returns the parent directory of this file.  If
124   * <code>file_ref</code> points to the root of the filesystem, then the root
125   * is returned.
126   *
127   * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
128   * reference.
129   *
130   * @return A <code>PP_Resource</code> containing the parent directory of the
131   * file. This function fails if the file system type is
132   * <code>PP_FileSystemType_External</code>.
133   */
134  PP_Resource (*GetParent)(PP_Resource file_ref);
135  /**
136   * MakeDirectory() makes a new directory in the file system according to the
137   * given <code>make_directory_flags</code>, which is a bit-mask of the
138   * <code>PP_MakeDirectoryFlags</code> values.  It is not valid to make a
139   * directory in the external file system.
140   *
141   * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
142   * reference.
143   * @param[in] make_directory_flags A bit-mask of the
144   * <code>PP_MakeDirectoryFlags</code> values.
145   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
146   * completion of MakeDirectory().
147   *
148   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
149   */
150  int32_t (*MakeDirectory)(PP_Resource directory_ref,
151                           int32_t make_directory_flags,
152                           struct PP_CompletionCallback callback);
153  /**
154   * Touch() Updates time stamps for a file.  You must have write access to the
155   * file if it exists in the external filesystem.
156   *
157   * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
158   * reference.
159   * @param[in] last_access_time The last time the file was accessed.
160   * @param[in] last_modified_time The last time the file was modified.
161   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
162   * completion of Touch().
163   *
164   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
165   */
166  int32_t (*Touch)(PP_Resource file_ref,
167                   PP_Time last_access_time,
168                   PP_Time last_modified_time,
169                   struct PP_CompletionCallback callback);
170  /**
171   * Delete() deletes a file or directory. If <code>file_ref</code> refers to
172   * a directory, then the directory must be empty. It is an error to delete a
173   * file or directory that is in use.  It is not valid to delete a file in
174   * the external file system.
175   *
176   * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
177   * reference.
178   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
179   * completion of Delete().
180   *
181   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
182   */
183  int32_t (*Delete)(PP_Resource file_ref,
184                    struct PP_CompletionCallback callback);
185  /**
186   * Rename() renames a file or directory.  Arguments <code>file_ref</code> and
187   * <code>new_file_ref</code> must both refer to files in the same file
188   * system. It is an error to rename a file or directory that is in use.  It
189   * is not valid to rename a file in the external file system.
190   *
191   * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
192   * reference.
193   * @param[in] new_file_ref A <code>PP_Resource</code> corresponding to a new
194   * file reference.
195   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
196   * completion of Rename().
197   *
198   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
199   */
200  int32_t (*Rename)(PP_Resource file_ref,
201                    PP_Resource new_file_ref,
202                    struct PP_CompletionCallback callback);
203  /**
204   * Query() queries info about a file or directory. You must have access to
205   * read this file or directory if it exists in the external filesystem.
206   *
207   * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
208   * reference.
209   * @param[out] info A pointer to a <code>PP_FileInfo</code> which will be
210   * populated with information about the file or directory.
211   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
212   * completion of Query().
213   *
214   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
215   */
216  int32_t (*Query)(PP_Resource file_ref,
217                   struct PP_FileInfo* info,
218                   struct PP_CompletionCallback callback);
219  /**
220   * ReadDirectoryEntries() reads all entries in a directory.
221   *
222   * @param[in] file_ref A <code>PP_Resource</code> corresponding to a directory
223   * reference.
224   * @param[in] output An output array which will receive
225   * <code>PP_DirectoryEntry</code> objects on success.
226   * @param[in] callback A <code>PP_CompletionCallback</code> to run on
227   * completion.
228   *
229   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
230   */
231  int32_t (*ReadDirectoryEntries)(PP_Resource file_ref,
232                                  struct PP_ArrayOutput output,
233                                  struct PP_CompletionCallback callback);
234};
235
236typedef struct PPB_FileRef_1_2 PPB_FileRef;
237
238struct PPB_FileRef_1_0 {
239  PP_Resource (*Create)(PP_Resource file_system, const char* path);
240  PP_Bool (*IsFileRef)(PP_Resource resource);
241  PP_FileSystemType (*GetFileSystemType)(PP_Resource file_ref);
242  struct PP_Var (*GetName)(PP_Resource file_ref);
243  struct PP_Var (*GetPath)(PP_Resource file_ref);
244  PP_Resource (*GetParent)(PP_Resource file_ref);
245  int32_t (*MakeDirectory)(PP_Resource directory_ref,
246                           PP_Bool make_ancestors,
247                           struct PP_CompletionCallback callback);
248  int32_t (*Touch)(PP_Resource file_ref,
249                   PP_Time last_access_time,
250                   PP_Time last_modified_time,
251                   struct PP_CompletionCallback callback);
252  int32_t (*Delete)(PP_Resource file_ref,
253                    struct PP_CompletionCallback callback);
254  int32_t (*Rename)(PP_Resource file_ref,
255                    PP_Resource new_file_ref,
256                    struct PP_CompletionCallback callback);
257};
258
259struct PPB_FileRef_1_1 {
260  PP_Resource (*Create)(PP_Resource file_system, const char* path);
261  PP_Bool (*IsFileRef)(PP_Resource resource);
262  PP_FileSystemType (*GetFileSystemType)(PP_Resource file_ref);
263  struct PP_Var (*GetName)(PP_Resource file_ref);
264  struct PP_Var (*GetPath)(PP_Resource file_ref);
265  PP_Resource (*GetParent)(PP_Resource file_ref);
266  int32_t (*MakeDirectory)(PP_Resource directory_ref,
267                           PP_Bool make_ancestors,
268                           struct PP_CompletionCallback callback);
269  int32_t (*Touch)(PP_Resource file_ref,
270                   PP_Time last_access_time,
271                   PP_Time last_modified_time,
272                   struct PP_CompletionCallback callback);
273  int32_t (*Delete)(PP_Resource file_ref,
274                    struct PP_CompletionCallback callback);
275  int32_t (*Rename)(PP_Resource file_ref,
276                    PP_Resource new_file_ref,
277                    struct PP_CompletionCallback callback);
278  int32_t (*Query)(PP_Resource file_ref,
279                   struct PP_FileInfo* info,
280                   struct PP_CompletionCallback callback);
281  int32_t (*ReadDirectoryEntries)(PP_Resource file_ref,
282                                  struct PP_ArrayOutput output,
283                                  struct PP_CompletionCallback callback);
284};
285/**
286 * @}
287 */
288
289#endif  /* PPAPI_C_PPB_FILE_REF_H_ */
290
291