native_client_sdk/src/libraries/nacl_io/nacl_io.h

   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 #ifndef LIBRARIES_NACL_IO_NACL_IO_H_
   6 #define LIBRARIES_NACL_IO_NACL_IO_H_
   7
   8 #include <ppapi/c/pp_instance.h>
   9 #include <ppapi/c/ppb.h>
  10
  11 #include "nacl_io/ostypes.h"
  12 #include "sdk_util/macros.h"
  13
  14 EXTERN_C_BEGIN
  15
  16 typedef void (*nacl_io_exit_callback_t)(int status, void* user_data);
  17
  18 typedef void (*nacl_io_mount_callback_t)(const char* source,
  19                                          const char* target,
  20                                          const char* filesystemtype,
  21                                          unsigned long mountflags,
  22                                          const void* data,
  23                                          dev_t dev,
  24                                          void* user_data);
  25
  26 /**
  27  * Initialize nacl_io.
  28  *
  29  * NOTE: If you initialize nacl_io with this constructor, you cannot
  30  * use any filesystems that require PPAPI; e.g. persistent storage, etc.
  31  */
  32 int nacl_io_init(void);
  33
  34 /**
  35  * Initialize nacl_io with PPAPI support.
  36  *
  37  * Usage:
  38  *   PP_Instance instance;
  39  *   PPB_GetInterface get_interface;
  40  *   nacl_io_init(instance, get_interface);
  41  *
  42  * If you are using the PPAPI C interface:
  43  *   |instance| is passed to your instance in the DidCreate function.
  44  *   |get_interface| is passed to your module in the PPP_InitializeModule
  45  *   function.
  46  *
  47  * If you are using the PPAPI C++ interface:
  48  *   |instance| can be retrieved via the pp::Instance::pp_instance() method.
  49  *   |get_interface| can be retrieved via
  50  *       pp::Module::Get()->get_browser_interface()
  51  */
  52 int nacl_io_init_ppapi(PP_Instance instance, PPB_GetInterface get_interface);
  53
  54 /**
  55  * Uninitialize nacl_io.
  56  *
  57  * This removes interception for POSIX C-library function and releases
  58  * any associated resources.
  59  */
  60 int nacl_io_uninit(void);
  61
  62 void nacl_io_set_exit_callback(nacl_io_exit_callback_t exit_callback,
  63                                void* user_data);
  64
  65 /**
  66  * Mount a new filesystem type.
  67  *
  68  * This function is declared in <sys/mount.h>, but we document it here
  69  * because nacl_io is controlled primarily through mount(2)/umount(2).
  70  *
  71  * Some parameters are dependent on the filesystem type being mounted.
  72  *
  73  * The |data| parameter, if used, is always parsed as a string of comma
  74  * separated key-value pairs:
  75  *   e.g. "key1=param1,key2=param2"
  76  *
  77  *
  78  * filesystem types:
  79  *   "memfs": An in-memory filesystem.
  80  *     source: Unused.
  81  *     data: Unused.
  82  *
  83  *   "dev": A filesystem with various utility nodes. Some examples:
  84  *          "null": equivalent to /dev/null.
  85  *          "zero": equivalent to /dev/zero.
  86  *          "urandom": equivalent to /dev/urandom.
  87  *          "console[0-3]": logs to the JavaScript console with varying log
  88  *              levels.
  89  *          "tty": Posts a message to JavaScript, which will send a "message"
  90  *              event from this module's embed element.
  91  *     source: Unused.
  92  *     data: Unused.
  93  *
  94  *   "html5fs": A filesystem that uses PPAPI FileSystem interface, which can be
  95  *              read in JavaScript via the HTML5 FileSystem API. This filesystem
  96  *              provides the use of persistent storage. Please read the
  97  *              documentation in ppapi/c/ppb_file_system.h for more information.
  98  *     source: Used to mount a subtree of the filesystem. Necessary when
  99  *             mounting non-sandboxed filesystems provided from javascript (e.g.
 100  *             via chrome.fileSystem in a chrome app). This should be a path
 101  *             which will be transparently prepended to all paths when
 102  *             performing the underlying file operations.
 103  *     data: A string of parameters:
 104  *       "type": Which type of filesystem to mount. Valid values are
 105  *           "PERSISTENT" and "TEMPORARY". The default is "PERSISTENT".
 106  *       "expected_size": The expected file-system size. Note that this does
 107  *           not request quota -- you must do that from JavaScript.
 108  *       "filesystem_resource": If specified, this is a string that contains
 109  *           the integer ID of the Filesystem resource to use instead of
 110  *           creating a new one. The "type" and "expected_size" parameters are
 111  *           ignored in this case. This parameter is useful when you pass a
 112  *           Filesystem resource from JavaScript, but still want to be able to
 113  *           call open/read/write/etc.
 114  *
 115  *   "httpfs": A filesystem that reads from a URL via HTTP.
 116  *     source: The root URL to read from. All paths read from this filesystem
 117  *             will be appended to this root.
 118  *             e.g. If source == "http://example.com/path", reading from
 119  *             "foo/bar.txt" will attempt to read from the URL
 120  *             "http://example.com/path/foo/bar.txt".
 121  *     data: A string of parameters:
 122  *       "allow_cross_origin_requests": If "true", then reads from this
 123  *           filesystem will follow the CORS standard for cross-origin requests.
 124  *           See http://www.w3.org/TR/access-control.
 125  *       "allow_credentials": If "true", credentials are sent with cross-origin
 126  *           requests. If false, no credentials are sent with the request and
 127  *           cookies are ignored in the response.
 128  *       All other key/value pairs are assumed to be headers to use with
 129  *       HTTP requests.
 130  *
 131  *   "passthroughfs": A filesystem that passes all requests through to the
 132  *                    underlying NaCl calls. The primary use of this filesystem
 133  *                    is to allow reading NMF resources.
 134  *     source: Unused.
 135  *     data: Unused.
 136  *
 137  *
 138  * @param[in] source Depends on the filesystem type. See above.
 139  * @param[in] target The absolute path to mount the filesystem.
 140  * @param[in] filesystemtype The name of the filesystem type to mount. See
 141  *     above for examples.
 142  * @param[in] mountflags Unused.
 143  * @param[in] data Depends on the filesystem type. See above.
 144  * @return 0 on success, -1 on failure (with errno set).
 145  *
 146  * int mount(const char* source, const char* target, const char* filesystemtype,
 147  *         unsigned long mountflags, const void *data) NOTHROW;
 148  */
 149
 150 /**
 151  * Register a new filesystem type, using a FUSE interface to implement it.
 152  *
 153  * Example:
 154  *   int my_open(const char* path, struct fuse_file_info*) {
 155  *     ...
 156  *   }
 157  *
 158  *   int my_read(const char* path, char* buf, size_t count, off_t offset, struct
 159  *               fuse_file_info* info) {
 160  *     ...
 161  *   }
 162  *
 163  *   struct fuse_operations my_fuse_ops = {
 164  *     ...
 165  *     my_open,
 166  *     NULL,  // opendir() not implemented.
 167  *     my_read,
 168  *     ...
 169  *   };
 170  *
 171  *   ...
 172  *
 173  *   const char fs_type[] = "my_fs";
 174  *   int result = nacl_io_register_fs_type(fs_type, &my_fuse_ops);
 175  *   if (!result) {
 176  *     fprintf(stderr, "Error registering filesystem type %s.\n", fs_type);
 177  *     exit(1);
 178  *   }
 179  *
 180  *   ...
 181  *
 182  *   int result = mount("", "/fs/foo", fs_type, 0, NULL);
 183  *   if (!result) {
 184  *     fprintf(stderr, "Error mounting %s.\n", fs_type);
 185  *     exit(1);
 186  *   }
 187  *
 188  * See fuse.h for more information about the FUSE interface.
 189  * Also see fuse.sourceforge.net for more information about FUSE in general.
 190  *
 191  * @param[in] fs_type The name of the new filesystem type.
 192  * @param[in] fuse_ops A pointer to the FUSE interface that will be used to
 193  *     implement this filesystem type. This pointer must be valid for the
 194  *     lifetime of all filesystems and nodes that are created with it.
 195  * @return 0 on success, -1 on failure (with errno set).
 196  */
 197 struct fuse_operations;
 198 int nacl_io_register_fs_type(const char* fs_type,
 199                              struct fuse_operations* fuse_ops);
 200
 201 /**
 202  * Unregister a filesystem type, previously registered by
 203  * nacl_io_register_fs_type().
 204  *
 205  * @param[in] fs_type The name of the filesystem type; the same identifier that
 206  *     was passed to nacl_io_register_fs_type().
 207  * @return 0 on success, -1 on failure (with errno set).
 208  */
 209 int nacl_io_unregister_fs_type(const char* fs_type);
 210
 211 /**
 212  * Set a mount callback.
 213  *
 214  * This callback is called whenever mount() succeeds. This callback can be used
 215  * to get the dev number of the newly-mounted filesystem.
 216  *
 217  * @param[in] callback The callback to set, or NULL.
 218  * @param[in] user_data User data that will be passed to the callback.
 219  * @return 0 on success, -1 on failure.
 220  */
 221 void nacl_io_set_mount_callback(nacl_io_mount_callback_t callback,
 222                                 void* user_data);
 223
 224 EXTERN_C_END
 225
 226 #endif /* LIBRARIES_NACL_IO_NACL_IO_H_ */