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