ppb_file_ref.h revision c2e0dbddbe15c98d52c4786dac06cb8952a8ae6d 
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 Thu May  2 16:22:57 2013. */
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 PPB_FILEREF_INTERFACE_1_1
24
25/**
26 * @file
27 * This file defines the API to create a file reference or "weak pointer" to a
28 * file in a file system.
29 */
30
31
32/**
33 * @addtogroup Interfaces
34 * @{
35 */
36/**
37 * The <code>PPB_FileRef</code> struct represents a "weak pointer" to a file in
38 * a file system.  This struct contains a <code>PP_FileSystemType</code>
39 * identifier and a file path string.
40 */
41struct PPB_FileRef_1_1 {
42  /**
43   * Create() creates a weak pointer to a file in the given file system. File
44   * paths are POSIX style.
45   *
46   * @param[in] resource A <code>PP_Resource</code> corresponding to a file
47   * system.
48   * @param[in] path A path to the file.
49   *
50   * @return A <code>PP_Resource</code> corresponding to a file reference if
51   * successful or 0 if the path is malformed.
52   */
53  PP_Resource (*Create)(PP_Resource file_system, const char* path);
54  /**
55   * IsFileRef() determines if the provided resource is a file reference.
56   *
57   * @param[in] resource A <code>PP_Resource</code> corresponding to a file
58   * reference.
59   *
60   * @return <code>PP_TRUE</code> if the resource is a
61   * <code>PPB_FileRef</code>, <code>PP_FALSE</code> if the resource is
62   * invalid or some type other than <code>PPB_FileRef</code>.
63   */
64  PP_Bool (*IsFileRef)(PP_Resource resource);
65  /**
66   * GetFileSystemType() returns the type of the file system.
67   *
68   * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
69   * reference.
70   *
71   * @return A <code>PP_FileSystemType</code> with the file system type if
72   * valid or <code>PP_FILESYSTEMTYPE_INVALID</code> if the provided resource
73   * is not a valid file reference.
74   */
75  PP_FileSystemType (*GetFileSystemType)(PP_Resource file_ref);
76  /**
77   * GetName() returns the name of the file.
78   *
79   * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
80   * reference.
81   *
82   * @return A <code>PP_Var</code> containing the name of the file.  The value
83   * returned by this function does not include any path components (such as
84   * the name of the parent directory, for example). It is just the name of the
85   * file. Use GetPath() to get the full file path.
86   */
87  struct PP_Var (*GetName)(PP_Resource file_ref);
88  /**
89   * GetPath() returns the absolute path of the file.
90   *
91   * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
92   * reference.
93   *
94   * @return A <code>PP_Var</code> containing the absolute path of the file.
95   * This function fails if the file system type is
96   * <code>PP_FileSystemType_External</code>.
97   */
98  struct PP_Var (*GetPath)(PP_Resource file_ref);
99  /**
100   * GetParent() returns the parent directory of this file.  If
101   * <code>file_ref</code> points to the root of the filesystem, then the root
102   * is returned.
103   *
104   * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
105   * reference.
106   *
107   * @return A <code>PP_Resource</code> containing the parent directory of the
108   * file. This function fails if the file system type is
109   * <code>PP_FileSystemType_External</code>.
110   */
111  PP_Resource (*GetParent)(PP_Resource file_ref);
112  /**
113   * MakeDirectory() makes a new directory in the file system as well as any
114   * parent directories if the <code>make_ancestors</code> argument is
115   * <code>PP_TRUE</code>.  It is not valid to make a directory in the external
116   * file system.
117   *
118   * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
119   * reference.
120   * @param[in] make_ancestors A <code>PP_Bool</code> set to
121   * <code>PP_TRUE</code> to make ancestor directories or <code>PP_FALSE</code>
122   * if ancestor directories are not needed.
123   *
124   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
125   * Fails if the directory already exists or if ancestor directories do not
126   * exist and <code>make_ancestors</code> was not passed as
127   * <code>PP_TRUE</code>.
128   */
129  int32_t (*MakeDirectory)(PP_Resource directory_ref,
130                           PP_Bool make_ancestors,
131                           struct PP_CompletionCallback callback);
132  /**
133   * Touch() Updates time stamps for a file.  You must have write access to the
134   * file if it exists in the external filesystem.
135   *
136   * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
137   * reference.
138   * @param[in] last_access_time The last time the file was accessed.
139   * @param[in] last_modified_time The last time the file was modified.
140   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
141   * completion of Touch().
142   *
143   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
144   */
145  int32_t (*Touch)(PP_Resource file_ref,
146                   PP_Time last_access_time,
147                   PP_Time last_modified_time,
148                   struct PP_CompletionCallback callback);
149  /**
150   * Delete() deletes a file or directory. If <code>file_ref</code> refers to
151   * a directory, then the directory must be empty. It is an error to delete a
152   * file or directory that is in use.  It is not valid to delete a file in
153   * the external file system.
154   *
155   * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
156   * reference.
157   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
158   * completion of Delete().
159   *
160   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
161   */
162  int32_t (*Delete)(PP_Resource file_ref,
163                    struct PP_CompletionCallback callback);
164  /**
165   * Rename() renames a file or directory.  Arguments <code>file_ref</code> and
166   * <code>new_file_ref</code> must both refer to files in the same file
167   * system. It is an error to rename a file or directory that is in use.  It
168   * is not valid to rename a file in the external file system.
169   *
170   * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
171   * reference.
172   * @param[in] new_file_ref A <code>PP_Resource</code> corresponding to a new
173   * file reference.
174   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
175   * completion of Rename().
176   *
177   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
178   */
179  int32_t (*Rename)(PP_Resource file_ref,
180                    PP_Resource new_file_ref,
181                    struct PP_CompletionCallback callback);
182  /**
183   * Query() queries info about a file or directory. You must have access to
184   * read this file or directory if it exists in the external filesystem.
185   *
186   * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
187   * reference.
188   * @param[out] info A pointer to a <code>PP_FileInfo</code> which will be
189   * populated with information about the file or directory.
190   * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
191   * completion of Query().
192   *
193   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
194   */
195  int32_t (*Query)(PP_Resource file_ref,
196                   struct PP_FileInfo* info,
197                   struct PP_CompletionCallback callback);
198  /**
199   * ReadDirectoryEntries() reads all entries in a directory.
200   *
201   * @param[in] file_ref A <code>PP_Resource</code> corresponding to a directory
202   * reference.
203   * @param[in] output An output array which will receive
204   * <code>PP_DirectoryEntry</code> objects on success.
205   * @param[in] callback A <code>PP_CompletionCallback</code> to run on
206   * completion.
207   *
208   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
209   */
210  int32_t (*ReadDirectoryEntries)(PP_Resource file_ref,
211                                  struct PP_ArrayOutput output,
212                                  struct PP_CompletionCallback callback);
213};
214
215typedef struct PPB_FileRef_1_1 PPB_FileRef;
216
217struct PPB_FileRef_1_0 {
218  PP_Resource (*Create)(PP_Resource file_system, const char* path);
219  PP_Bool (*IsFileRef)(PP_Resource resource);
220  PP_FileSystemType (*GetFileSystemType)(PP_Resource file_ref);
221  struct PP_Var (*GetName)(PP_Resource file_ref);
222  struct PP_Var (*GetPath)(PP_Resource file_ref);
223  PP_Resource (*GetParent)(PP_Resource file_ref);
224  int32_t (*MakeDirectory)(PP_Resource directory_ref,
225                           PP_Bool make_ancestors,
226                           struct PP_CompletionCallback callback);
227  int32_t (*Touch)(PP_Resource file_ref,
228                   PP_Time last_access_time,
229                   PP_Time last_modified_time,
230                   struct PP_CompletionCallback callback);
231  int32_t (*Delete)(PP_Resource file_ref,
232                    struct PP_CompletionCallback callback);
233  int32_t (*Rename)(PP_Resource file_ref,
234                    PP_Resource new_file_ref,
235                    struct PP_CompletionCallback callback);
236};
237/**
238 * @}
239 */
240
241#endif  /* PPAPI_C_PPB_FILE_REF_H_ */
242
243