tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

PFileSystemManager.ipdl (10100B)

      1 /* This Source Code Form is subject to the terms of the Mozilla Public
      2  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
      3  * You can obtain one at http://mozilla.org/MPL/2.0/. */
      4 
      5 include protocol PFileSystemAccessHandle;
      6 include protocol PFileSystemAccessHandleControl;
      7 include protocol PFileSystemWritableFileStream;
      8 
      9 include IPCBlob;
     10 include RandomAccessStreamParams;
     11 
     12 using mozilla::dom::fs::ContentType from "mozilla/dom/FileSystemTypes.h";
     13 using mozilla::dom::fs::EntryId from "mozilla/dom/FileSystemTypes.h";
     14 using mozilla::dom::fs::Name from "mozilla/dom/FileSystemTypes.h";
     15 using mozilla::dom::fs::Origin from "mozilla/dom/FileSystemTypes.h";
     16 using mozilla::dom::fs::PageNumber from "mozilla/dom/FileSystemTypes.h";
     17 using mozilla::dom::fs::TimeStamp from "mozilla/dom/FileSystemTypes.h";
     18 using struct mozilla::void_t from "mozilla/ipc/IPCCore.h";
     19 
     20 namespace mozilla {
     21 namespace dom {
     22 namespace fs {
     23 
     24 /**
     25  * Identifies a file or a directory and contains its user provided name.
     26  */
     27 struct FileSystemEntryMetadata
     28 {
     29   EntryId entryId;
     30   Name entryName;
     31   bool directory;
     32 };
     33 
     34 /**
     35  * Identifies a file or a directory with its parent identifier and
     36  * user provided name.
     37  */
     38 struct FileSystemChildMetadata
     39 {
     40   EntryId parentId;
     41   Name childName;
     42 };
     43 
     44 /**
     45  * Identifies a file with its parent directory and name, and
     46  * indicates whether the file may be created if it is missing.
     47  */
     48 struct FileSystemGetHandleRequest
     49 {
     50   FileSystemChildMetadata handle;
     51   bool create;
     52 };
     53 
     54 /**
     55  * Contains a file or directory or an error.
     56  */
     57 union FileSystemGetHandleResponse
     58 {
     59   nsresult;
     60   EntryId;
     61 };
     62 
     63 /**
     64  * Contains an identifier for a parent directory and a page number
     65  * which is used to fetch the next set of entries when the directory
     66  * contains so many items that communicating all of them in one message
     67  * is an impractical.
     68  */
     69 struct FileSystemGetEntriesRequest
     70 {
     71   EntryId parentId;
     72   PageNumber page;
     73 };
     74 
     75 /**
     76  * Contains a set of directories and files
     77  * under the same parent directory.
     78  */
     79 struct FileSystemDirectoryListing
     80 {
     81   FileSystemEntryMetadata[] directories;
     82   FileSystemEntryMetadata[] files;
     83 };
     84 
     85 /**
     86  * Contains a set of entries or an error.
     87  */
     88 union FileSystemGetEntriesResponse
     89 {
     90   nsresult;
     91   FileSystemDirectoryListing;
     92 };
     93 
     94 /**
     95  * Contains entry handle information.
     96  */
     97 struct FileSystemGetFileRequest
     98 {
     99   EntryId entryId;
    100 };
    101 
    102 /**
    103  * Contains the properties of a file and a file descriptor.
    104  * The properties may differ from the properties of the
    105  * underlying object of the file descriptor.
    106  */
    107 struct FileSystemFileProperties
    108 {
    109   TimeStamp last_modified_ms;
    110   IPCBlob file;
    111   ContentType type;
    112   Name[] path;
    113 };
    114 
    115 /**
    116  * Contains file properties or an error.
    117  */
    118 union FileSystemGetFileResponse
    119 {
    120   nsresult;
    121   FileSystemFileProperties;
    122 };
    123 
    124 /**
    125  * Contains entry handle information.
    126  */
    127 struct FileSystemGetAccessHandleRequest
    128 {
    129   EntryId entryId;
    130 };
    131 
    132 struct FileSystemAccessHandleProperties
    133 {
    134   RandomAccessStreamParams streamParams;
    135   ManagedEndpoint<PFileSystemAccessHandleChild> accessHandleChildEndpoint;
    136   Endpoint<PFileSystemAccessHandleControlChild> accessHandleControlChildEndpoint;
    137 };
    138 
    139 union FileSystemGetAccessHandleResponse
    140 {
    141   nsresult;
    142   FileSystemAccessHandleProperties;
    143 };
    144 
    145 /**
    146  * Contains entry handle information.
    147  */
    148 struct FileSystemGetWritableRequest
    149 {
    150   EntryId entryId;
    151   bool keepData;
    152 };
    153 
    154 struct FileSystemWritableFileStreamProperties
    155 {
    156   RandomAccessStreamParams streamParams;
    157   PFileSystemWritableFileStream writableFileStream;
    158 };
    159 
    160 union FileSystemGetWritableFileStreamResponse
    161 {
    162   nsresult;
    163   FileSystemWritableFileStreamProperties;
    164 };
    165 
    166 /**
    167  * Represents a pair of file system entries which
    168  * are not necessarily connected by a path.
    169  */
    170 struct FileSystemEntryPair
    171 {
    172   EntryId parentId;
    173   EntryId childId;
    174 };
    175 
    176 /**
    177  * Contains a pair of file system entries.
    178  */
    179 struct FileSystemResolveRequest
    180 {
    181   FileSystemEntryPair endpoints;
    182 };
    183 
    184 /**
    185  * Contains a file system path.
    186  */
    187 struct FileSystemPath
    188 {
    189   Name[] path;
    190 };
    191 
    192 /**
    193  * Contains a potentially empty path or an error.
    194  */
    195 union FileSystemResolveResponse
    196 {
    197   nsresult;
    198   FileSystemPath?;
    199 };
    200 
    201 /**
    202  * Identifies a file with its parent directory and name, and
    203  * indicates whether all the children of a directory may be removed.
    204  */
    205 struct FileSystemRemoveEntryRequest
    206 {
    207   FileSystemChildMetadata handle;
    208   bool recursive;
    209 };
    210 
    211 /**
    212  * Contains an error or nothing.
    213  */
    214 union FileSystemRemoveEntryResponse
    215 {
    216   nsresult;
    217   void_t;
    218 };
    219 
    220 /**
    221  * Identifies a file/directory to be moved and the new name, and the
    222  * destination directory
    223  */
    224 struct FileSystemMoveEntryRequest
    225 {
    226   FileSystemEntryMetadata handle;
    227   FileSystemChildMetadata destHandle;
    228 };
    229 
    230 /**
    231  * Identifies a file/directory to be renamed and the new name
    232  */
    233 struct FileSystemRenameEntryRequest
    234 {
    235   FileSystemEntryMetadata handle;
    236   Name name;
    237 };
    238 
    239 /**
    240  * Contains an error or the new entryId
    241  */
    242 union FileSystemMoveEntryResponse
    243 {
    244   nsresult;
    245   EntryId;
    246 };
    247 
    248 }  // namespace fs
    249 
    250 [ChildProc=anydom]
    251 async protocol PFileSystemManager
    252 {
    253   manages PFileSystemAccessHandle;
    254   manages PFileSystemWritableFileStream;
    255 
    256  parent:
    257   /**
    258    * TODO: documentation
    259    */
    260   [VirtualSendImpl]
    261   async GetRootHandle()
    262       returns(FileSystemGetHandleResponse response);
    263 
    264   /**
    265    * Initiates an asynchronous request for the handle of
    266    * a subdirectory with a given name under the current directory.
    267    *
    268    * Invalid names are rejected with an appropriate error.
    269    *
    270    * If the subdirectory exists, a handle to it is always returned.
    271    *
    272    * If no child of any kind with the given name exists and
    273    * the create-flag of the input is set, the subdirectory will be created,
    274    * otherwise an appropriate error is returned.
    275    *
    276    * @param[in] handle request containing a create flag
    277    *
    278    * @returns error or entry handle
    279    */
    280   [VirtualSendImpl]
    281   async GetDirectoryHandle(FileSystemGetHandleRequest request)
    282       returns(FileSystemGetHandleResponse handle);
    283 
    284   /**
    285    * Initiates an asynchronous request for the handle to
    286    * a file with a given name under the current directory.
    287    *
    288    * Invalid names are rejected with an appropriate error.
    289    *
    290    * If the file exists, a handle to it is always returned.
    291    *
    292    * If no child of any kind with the given name exists and
    293    * the create-flag of the input is set, the file will be created,
    294    * otherwise an appropriate error is returned.
    295    *
    296    * @param[in] handle request containing a create flag
    297    *
    298    * @returns error or entry handle
    299    */
    300   [VirtualSendImpl]
    301   async GetFileHandle(FileSystemGetHandleRequest request)
    302       returns(FileSystemGetHandleResponse handle);
    303 
    304   /**
    305    * Initiates an asynchronous request for a read-only object representing the
    306    * file corresponding to the current file handle.
    307    *
    308    * The returned object provides read-only access.
    309    *
    310    * If the underlying file object is modified through a mutable interface,
    311    * the returned value is considered stale. Concurrent changes are not
    312    * guaranteed to be visible or invisible. Using a stale object
    313    * returns appropriate errors when the results are unpredictable.
    314    *
    315    * @param[in] request for a file object
    316    *
    317    * @returns error or file object
    318    */
    319   [VirtualSendImpl]
    320   async GetFile(FileSystemGetFileRequest request)
    321       returns(FileSystemGetFileResponse response);
    322 
    323   /**
    324    * TODO: documentation
    325    */
    326   [VirtualSendImpl]
    327   async GetAccessHandle(FileSystemGetAccessHandleRequest request)
    328       returns(FileSystemGetAccessHandleResponse response);
    329 
    330   /**
    331    * TODO: documentation
    332    */
    333   [VirtualSendImpl]
    334   async GetWritable(FileSystemGetWritableRequest request)
    335       returns(FileSystemGetWritableFileStreamResponse fileData);
    336 
    337   /**
    338    * Initiates an asynchronous request for the file system path
    339    * associated with a file system entry.
    340    *
    341    * @param[in] request identifying a file object
    342    *
    343    * @returns error or file system path
    344    */
    345   [VirtualSendImpl]
    346   async Resolve(FileSystemResolveRequest request)
    347       returns(FileSystemResolveResponse response);
    348 
    349   /**
    350    * Initiates an asynchronous request for an iterator to the child entries
    351    * under the calling directory handle.
    352    *
    353    * If the directory item names or the directory structure is modified while
    354    * the iterator is in use, the iterator remains safe to use but no guarantees
    355    * are made regarding the visibility of the concurrent changes.
    356    * It is possible that a file which is added after the iteration has begun
    357    * will not be returned, or that among the values there are invalid file
    358    * handles whose underlying objects have been removed after the iteration
    359    * started.
    360    *
    361    * @param[in] request for a iterator
    362    *
    363    * @returns error or iterator
    364    */
    365   [VirtualSendImpl]
    366   async GetEntries(FileSystemGetEntriesRequest request)
    367       returns(FileSystemGetEntriesResponse entries);
    368 
    369   /**
    370    * Initiates an asynchronous request to delete a directory or file with a
    371    * given name under the calling directory handle.
    372    *
    373    * If recursive flag of the request is not set, a request to remove a
    374    * non-empty directory returns an appropriate error, otherwise all the child
    375    * files and directories are made to vanish.
    376    *
    377    * The recursive flag has no impact on files.
    378    *
    379    * @param[in] request containing a recursive flag
    380    *
    381    * @returns error information
    382    */
    383   [VirtualSendImpl]
    384   async RemoveEntry(FileSystemRemoveEntryRequest request)
    385       returns(FileSystemRemoveEntryResponse response);
    386 
    387   /**
    388    * Initiates an asynchronous request to move a directory or file with a
    389    * given name to a given destination and new name.
    390    *
    391    * @returns error information
    392    */
    393   async MoveEntry(FileSystemMoveEntryRequest request)
    394       returns(FileSystemMoveEntryResponse response);
    395 
    396   /**
    397    * Initiates an asynchronous request to rename a directory or file
    398    *
    399    * @returns error information
    400    */
    401   async RenameEntry(FileSystemRenameEntryRequest request)
    402       returns(FileSystemMoveEntryResponse response);
    403 
    404  child:
    405   async PFileSystemWritableFileStream();
    406 
    407   async CloseAll()
    408       returns(nsresult rv);
    409 };
    410 
    411 } // namespace dom
    412 } // namespace mozilla
    413