summaryrefslogtreecommitdiffstats
path: root/dom/fs/shared/PFileSystemManager.ipdl
blob: 9058820fd245704f5a01f639bc89e0644f7f35da (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this file,
 * You can obtain one at http://mozilla.org/MPL/2.0/. */

include protocol PFileSystemAccessHandle;
include protocol PFileSystemAccessHandleControl;
include protocol PFileSystemWritableFileStream;

include IPCBlob;
include RandomAccessStreamParams;

using mozilla::dom::fs::ContentType from "mozilla/dom/FileSystemTypes.h";
using mozilla::dom::fs::EntryId from "mozilla/dom/FileSystemTypes.h";
using mozilla::dom::fs::Name from "mozilla/dom/FileSystemTypes.h";
using mozilla::dom::fs::Origin from "mozilla/dom/FileSystemTypes.h";
using mozilla::dom::fs::PageNumber from "mozilla/dom/FileSystemTypes.h";
using mozilla::dom::fs::TimeStamp from "mozilla/dom/FileSystemTypes.h";
using struct mozilla::void_t from "mozilla/ipc/IPCCore.h";

namespace mozilla {
namespace dom {
namespace fs {

/**
 * Identifies a file or a directory and contains its user provided name.
 */
struct FileSystemEntryMetadata
{
  EntryId entryId;
  Name entryName;
  bool directory;
};

/**
 * Identifies a file or a directory with its parent identifier and
 * user provided name.
 */
struct FileSystemChildMetadata
{
  EntryId parentId;
  Name childName;
};

/**
 * Identifies a file with its parent directory and name, and
 * indicates whether the file may be created if it is missing.
 */
struct FileSystemGetHandleRequest
{
  FileSystemChildMetadata handle;
  bool create;
};

/**
 * Contains a file or directory or an error.
 */
union FileSystemGetHandleResponse
{
  nsresult;
  EntryId;
};

/**
 * Contains an identifier for a parent directory and a page number
 * which is used to fetch the next set of entries when the directory
 * contains so many items that communicating all of them in one message
 * is an impractical.
 */
struct FileSystemGetEntriesRequest
{
  EntryId parentId;
  PageNumber page;
};

/**
 * Contains a set of directories and files
 * under the same parent directory.
 */
struct FileSystemDirectoryListing
{
  FileSystemEntryMetadata[] directories;
  FileSystemEntryMetadata[] files;
};

/**
 * Contains a set of entries or an error.
 */
union FileSystemGetEntriesResponse
{
  nsresult;
  FileSystemDirectoryListing;
};

/**
 * Contains entry handle information.
 */
struct FileSystemGetFileRequest
{
  EntryId entryId;
};

/**
 * Contains the properties of a file and a file descriptor.
 * The properties may differ from the properties of the
 * underlying object of the file descriptor.
 */
struct FileSystemFileProperties
{
  TimeStamp last_modified_ms;
  IPCBlob file;
  ContentType type;
  Name[] path;
};

/**
 * Contains file properties or an error.
 */
union FileSystemGetFileResponse
{
  nsresult;
  FileSystemFileProperties;
};

/**
 * Contains entry handle information.
 */
struct FileSystemGetAccessHandleRequest
{
  EntryId entryId;
};

struct FileSystemAccessHandleProperties
{
  RandomAccessStreamParams streamParams;
  ManagedEndpoint<PFileSystemAccessHandleChild> accessHandleChildEndpoint;
  Endpoint<PFileSystemAccessHandleControlChild> accessHandleControlChildEndpoint;
};

union FileSystemGetAccessHandleResponse
{
  nsresult;
  FileSystemAccessHandleProperties;
};

/**
 * Contains entry handle information.
 */
struct FileSystemGetWritableRequest
{
  EntryId entryId;
  bool keepData;
};

struct FileSystemWritableFileStreamProperties
{
  RandomAccessStreamParams streamParams;
  PFileSystemWritableFileStream writableFileStream;
};

union FileSystemGetWritableFileStreamResponse
{
  nsresult;
  FileSystemWritableFileStreamProperties;
};

/**
 * Represents a pair of file system entries which
 * are not necessarily connected by a path.
 */
struct FileSystemEntryPair
{
  EntryId parentId;
  EntryId childId;
};

/**
 * Contains a pair of file system entries.
 */
struct FileSystemResolveRequest
{
  FileSystemEntryPair endpoints;
};

/**
 * Contains a file system path.
 */
struct FileSystemPath
{
  Name[] path;
};

/**
 * Contains a potentially empty path or an error.
 */
union FileSystemResolveResponse
{
  nsresult;
  FileSystemPath?;
};

/**
 * Identifies a file with its parent directory and name, and
 * indicates whether all the children of a directory may be removed.
 */
struct FileSystemRemoveEntryRequest
{
  FileSystemChildMetadata handle;
  bool recursive;
};

/**
 * Contains an error or nothing.
 */
union FileSystemRemoveEntryResponse
{
  nsresult;
  void_t;
};

/**
 * Identifies a file/directory to be moved and the new name, and the
 * destination directory
 */
struct FileSystemMoveEntryRequest
{
  FileSystemEntryMetadata handle;
  FileSystemChildMetadata destHandle;
};

/**
 * Identifies a file/directory to be renamed and the new name
 */
struct FileSystemRenameEntryRequest
{
  FileSystemEntryMetadata handle;
  Name name;
};

/**
 * Contains an error or the new entryId
 */
union FileSystemMoveEntryResponse
{
  nsresult;
  EntryId;
};

}  // namespace fs

[ChildProc=anydom]
async protocol PFileSystemManager
{
  manages PFileSystemAccessHandle;
  manages PFileSystemWritableFileStream;

 parent:
  /**
   * TODO: documentation
   */
  [VirtualSendImpl]
  async GetRootHandle()
      returns(FileSystemGetHandleResponse response);

  /**
   * Initiates an asynchronous request for the handle of
   * a subdirectory with a given name under the current directory.
   *
   * Invalid names are rejected with an appropriate error.
   *
   * If the subdirectory exists, a handle to it is always returned.
   *
   * If no child of any kind with the given name exists and
   * the create-flag of the input is set, the subdirectory will be created,
   * otherwise an appropriate error is returned.
   *
   * @param[in] handle request containing a create flag
   *
   * @returns error or entry handle
   */
  [VirtualSendImpl]
  async GetDirectoryHandle(FileSystemGetHandleRequest request)
      returns(FileSystemGetHandleResponse handle);

  /**
   * Initiates an asynchronous request for the handle to
   * a file with a given name under the current directory.
   *
   * Invalid names are rejected with an appropriate error.
   *
   * If the file exists, a handle to it is always returned.
   *
   * If no child of any kind with the given name exists and
   * the create-flag of the input is set, the file will be created,
   * otherwise an appropriate error is returned.
   *
   * @param[in] handle request containing a create flag
   *
   * @returns error or entry handle
   */
  [VirtualSendImpl]
  async GetFileHandle(FileSystemGetHandleRequest request)
      returns(FileSystemGetHandleResponse handle);

  /**
   * Initiates an asynchronous request for a read-only object representing the
   * file corresponding to the current file handle.
   *
   * The returned object provides read-only access.
   *
   * If the underlying file object is modified through a mutable interface,
   * the returned value is considered stale. Concurrent changes are not
   * guaranteed to be visible or invisible. Using a stale object
   * returns appropriate errors when the results are unpredictable.
   *
   * @param[in] request for a file object
   *
   * @returns error or file object
   */
  [VirtualSendImpl]
  async GetFile(FileSystemGetFileRequest request)
      returns(FileSystemGetFileResponse response);

  /**
   * TODO: documentation
   */
  [VirtualSendImpl]
  async GetAccessHandle(FileSystemGetAccessHandleRequest request)
      returns(FileSystemGetAccessHandleResponse response);

  /**
   * TODO: documentation
   */
  [VirtualSendImpl]
  async GetWritable(FileSystemGetWritableRequest request)
      returns(FileSystemGetWritableFileStreamResponse fileData);

  /**
   * Initiates an asynchronous request for the file system path
   * associated with a file system entry.
   *
   * @param[in] request identifying a file object
   *
   * @returns error or file system path
   */
  [VirtualSendImpl]
  async Resolve(FileSystemResolveRequest request)
      returns(FileSystemResolveResponse response);

  /**
   * Initiates an asynchronous request for an iterator to the child entries
   * under the calling directory handle.
   *
   * If the directory item names or the directory structure is modified while
   * the iterator is in use, the iterator remains safe to use but no guarantees
   * are made regarding the visibility of the concurrent changes.
   * It is possible that a file which is added after the iteration has begun
   * will not be returned, or that among the values there are invalid file
   * handles whose underlying objects have been removed after the iteration
   * started.
   *
   * @param[in] request for a iterator
   *
   * @returns error or iterator
   */
  [VirtualSendImpl]
  async GetEntries(FileSystemGetEntriesRequest request)
      returns(FileSystemGetEntriesResponse entries);

  /**
   * Initiates an asynchronous request to delete a directory or file with a
   * given name under the calling directory handle.
   *
   * If recursive flag of the request is not set, a request to remove a
   * non-empty directory returns an appropriate error, otherwise all the child
   * files and directories are made to vanish.
   *
   * The recursive flag has no impact on files.
   *
   * @param[in] request containing a recursive flag
   *
   * @returns error information
   */
  [VirtualSendImpl]
  async RemoveEntry(FileSystemRemoveEntryRequest request)
      returns(FileSystemRemoveEntryResponse response);

  /**
   * Initiates an asynchronous request to move a directory or file with a
   * given name to a given destination and new name.
   *
   * @returns error information
   */
  async MoveEntry(FileSystemMoveEntryRequest request)
      returns(FileSystemMoveEntryResponse response);

  /**
   * Initiates an asynchronous request to rename a directory or file
   *
   * @returns error information
   */
  async RenameEntry(FileSystemRenameEntryRequest request)
      returns(FileSystemMoveEntryResponse response);

 child:
  async PFileSystemWritableFileStream();

  async CloseAll()
      returns(nsresult rv);
};

} // namespace dom
} // namespace mozilla