nacl_io.h revision 46d4c2bc3267f3f028f39e7e311b0f89aba2e4fd 
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
13EXTERN_C_BEGIN
14
15typedef 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 */
23void 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 */
43void nacl_io_init_ppapi(PP_Instance instance, PPB_GetInterface get_interface);
44
45int 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 */
176struct fuse_operations;
177int 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 */
188int nacl_io_unregister_fs_type(const char* fs_type);
189
190EXTERN_C_END
191
192#endif /* LIBRARIES_NACL_IO_NACL_IO_H_ */
193