chrome/common/extensions/docs/templates/intros/fileSystemProvider.html

   1 <h2 id="manifest">Manifest</h2>
   2 <p>You must declare the "fileSystemProvider" permission and section
   3 in the <a href="manifest">extension manifest</a>
   4 to use the File System Provider API.
   5 For example:</p>
   6 <pre data-filename="manifest.json">
   7 {
   8   "name": "My {{platform}}",
   9   ...
  10   "permissions": [
  11     "fileSystemProvider"
  12   ],
  13   ...
  14   "file_system_provider_capabilities": {
  15     "configurable": true,
  16     "watchable": false,
  17     "multiple_mounts": true,
  18     <span id="manifest-source">"source": "network"</span>
  19   },
  20   ...
  21 }
  22 </pre>
  23
  24 <p class="api_reference">
  25 The <code>file_system_provider</code> section must be declared as follows:
  26 {{+partials.manifest_type
  27    type:apis.extensions.manifestTypes.byName.FileSystemProviderCapabilities /}}
  28 </p>
  29 <p>
  30 Files app uses above information in order to render related UI elements
  31 approprietly. For example, if <code>configurable</code> is set to
  32 </code>true</code>, then a menu item for configuring volumes will be rendered.
  33 Similarly, if <code>multiple_mounts</code> is set to <code>true</code>, then
  34 Files app will allow to add more than one mount points from the UI. If
  35 <code>watchable</code> is <code>false</code>, then a refresh button will be
  36 rendered. Note, that if possible you should add support for watchers, so
  37 changes on the file system can be reflected immediately and automatically.
  38 </p>
  39
  40 <h2 id="overview">Overview</h2>
  41 <p>
  42 File System Provider API allows extensions to support virtual file systems,
  43 which are available in the file manager on Chrome OS.
  44 Use cases include decompressing archives and accessing files in a cloud
  45 service other than Drive.
  46 </p>
  47
  48 <h2 id="archives">Mounting file systems</h2>
  49 <p>
  50 Providing extensions can either provide file system contents from an external
  51 source (such as a remote server or a USB device), or using a local file (such as
  52 an archive) as its input.
  53 </p>
  54 <p>
  55 {{?is_apps}}
  56 For file handlers, the providing extension should have a
  57 <a href="manifest/file_handlers">file_handlers</a> manifest entry in order
  58 to be launched when the file is selected in the file manager.
  59 When the extension is executed with a file to be handled, it has to mount a
  60 file system and start serving contents from the provided file.
  61 {{:is_apps}}
  62 In order to write file systems which are file handlers (source is
  63 <code>"file"</code>) the provider must be a packaged app, as the
  64 <code>onLaunched</code>event is not available to extensions.
  65 {{/is_apps}}
  66 </p>
  67 <p>
  68 If the source is network or a device, then the file system should be mounted
  69 when $(ref:onMountRequested) event is called.
  70 </p>
  71 <p>
  72   <table id="source-table">
  73     <tr>
  74       <th>
  75         <a href="#manifest-source">Source</a> of the file system data
  76       </th>
  77       <th>Entry point</th>
  78     </tr>
  79     <tr>
  80       <td>
  81         <code>"file"</code>
  82       </td>
  83       <td>
  84         {{?is_apps}}
  85           $(ref:app.runtime.onLaunched)
  86         {{:is_apps}}
  87           Available to <a href="/apps/fileSystemProvider#source-table">packaged
  88           apps</a> only.
  89         {{/is_apps}}
  90       </td>
  91     </tr>
  92     <tr>
  93       <td>
  94         <code>"device"</code> or <code>"network"</code>
  95       </td>
  96       <td>
  97         $(ref:onMountRequested)
  98       </td>
  99     </tr>
 100   </table>
 101 </p>
 102
 103 <h2 id="archives">Configuring file systems</h2>
 104 <p>
 105 Provided file systems once mounted can be configured via the
 106 $(ref:onConfigureRequested) event. It's especially useful for file systems which
 107 provide contents via network in order to set proper credentials. Handling this
 108 event is optional.
 109 </p>
 110
 111 <h2 id="archives">Life cycle</h2>
 112 <p>
 113 Provided file systems once mounted are remembered by Chrome and remounted
 114 automatically after reboot or restart. Hence, once a file system is
 115 $(ref:mount mounted) by a providing extension, it will stay until either the
 116 extension is unloaded, or the extension calls the $(ref:unmount) method.
 117 </p>
 118 {{?is_apps}}
 119 <p>
 120 In case of acting as a file handler, the handled file may need to be stored
 121 to access it after either a reboot, or suspending and resuming an event page
 122 of the providing extension. In such case $(ref:fileSystem.retainEntry) and
 123 $(ref:fileSystem.restoreEntry) should be used.
 124 </p>
 125 {{/is_apps}}