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