1
// Copyright 2011 The Closure Library Authors. All Rights Reserved.
2
//
3
// Licensed under the Apache License, Version 2.0 (the "License");
4
// you may not use this file except in compliance with the License.
5
// You may obtain a copy of the License at
6
//
7
//      http://www.apache.org/licenses/LICENSE-2.0
8
//
9
// Unless required by applicable law or agreed to in writing, software
10
// distributed under the License is distributed on an "AS-IS" BASIS,
11
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
// See the License for the specific language governing permissions and
13
// limitations under the License.
14

15
/**
16
 * @fileoverview Wrappers for the HTML5 File API. These wrappers closely mirror
17
 * the underlying APIs, but use Closure-style events and Deferred return values.
18
 * Their existence also makes it possible to mock the FileSystem API for testing
19
 * in browsers that don't support it natively.
20
 *
21
 * When adding public functions to anything under this namespace, be sure to add
22
 * its mock counterpart to goog.testing.fs.
23
 *
24
 */
25

26
goog.provide('goog.fs');
27

28
goog.require('goog.array');
29
goog.require('goog.async.Deferred');
30
goog.require('goog.fs.Error');
31
goog.require('goog.fs.FileReader');
32
goog.require('goog.fs.FileSystemImpl');
33
goog.require('goog.fs.url');
34
goog.require('goog.userAgent');
35

36

37
/**
38
 * Get a wrapped FileSystem object.
39
 *
40
 * @param {goog.fs.FileSystemType_} type The type of the filesystem to get.
41
 * @param {number} size The size requested for the filesystem, in bytes.
42
 * @return {!goog.async.Deferred} The deferred {@link goog.fs.FileSystem}. If an
43
 *     error occurs, the errback is called with a {@link goog.fs.Error}.
44
 * @private
45
 */
46
goog.fs.get_ = function(type, size) {
47
  var requestFileSystem =
48
      goog.global.requestFileSystem || goog.global.webkitRequestFileSystem;
49

50
  if (!goog.isFunction(requestFileSystem)) {
51
    return goog.async.Deferred.fail(new Error('File API unsupported'));
52
  }
53

54
  var d = new goog.async.Deferred();
55
  requestFileSystem(
56
      type, size, function(fs) { d.callback(new goog.fs.FileSystemImpl(fs)); },
57
      function(err) {
58
        d.errback(new goog.fs.Error(err, 'requesting filesystem'));
59
      });
60
  return d;
61
};
62

63

64
/**
65
 * The two types of filesystem.
66
 *
67
 * @enum {number}
68
 * @private
69
 */
70
goog.fs.FileSystemType_ = {
71
  /**
72
   * A temporary filesystem may be deleted by the user agent at its discretion.
73
   */
74
  TEMPORARY: 0,
75
  /**
76
   * A persistent filesystem will never be deleted without the user's or
77
   * application's authorization.
78
   */
79
  PERSISTENT: 1
80
};
81

82

83
/**
84
 * Returns a temporary FileSystem object. A temporary filesystem may be deleted
85
 * by the user agent at its discretion.
86
 *
87
 * @param {number} size The size requested for the filesystem, in bytes.
88
 * @return {!goog.async.Deferred} The deferred {@link goog.fs.FileSystem}. If an
89
 *     error occurs, the errback is called with a {@link goog.fs.Error}.
90
 */
91
goog.fs.getTemporary = function(size) {
92
  return goog.fs.get_(goog.fs.FileSystemType_.TEMPORARY, size);
93
};
94

95

96
/**
97
 * Returns a persistent FileSystem object. A persistent filesystem will never be
98
 * deleted without the user's or application's authorization.
99
 *
100
 * @param {number} size The size requested for the filesystem, in bytes.
101
 * @return {!goog.async.Deferred} The deferred {@link goog.fs.FileSystem}. If an
102
 *     error occurs, the errback is called with a {@link goog.fs.Error}.
103
 */
104
goog.fs.getPersistent = function(size) {
105
  return goog.fs.get_(goog.fs.FileSystemType_.PERSISTENT, size);
106
};
107

108

109
/**
110
 * Creates a blob URL for a blob object.
111
 * Throws an error if the browser does not support Object Urls.
112
 *
113
 * TODO(user): Update references to this method to use
114
 * goog.fs.url.createObjectUrl instead.
115
 *
116
 * @param {!Blob} blob The object for which to create the URL.
117
 * @return {string} The URL for the object.
118
 */
119
goog.fs.createObjectUrl = function(blob) {
120
  return goog.fs.url.createObjectUrl(blob);
121
};
122

123

124
/**
125
 * Revokes a URL created by {@link goog.fs.createObjectUrl}.
126
 * Throws an error if the browser does not support Object Urls.
127
 *
128
 * TODO(user): Update references to this method to use
129
 * goog.fs.url.revokeObjectUrl instead.
130
 *
131
 * @param {string} url The URL to revoke.
132
 */
133
goog.fs.revokeObjectUrl = function(url) {
134
  goog.fs.url.revokeObjectUrl(url);
135
};
136

137

138
/**
139
 * Checks whether this browser supports Object Urls. If not, calls to
140
 * createObjectUrl and revokeObjectUrl will result in an error.
141
 *
142
 * TODO(user): Update references to this method to use
143
 * goog.fs.url.browserSupportsObjectUrls instead.
144
 *
145
 * @return {boolean} True if this browser supports Object Urls.
146
 */
147
goog.fs.browserSupportsObjectUrls = function() {
148
  return goog.fs.url.browserSupportsObjectUrls();
149
};
150

151

152
/**
153
 * Concatenates one or more values together and converts them to a Blob.
154
 *
155
 * @param {...(string|!Blob|!ArrayBuffer)} var_args The values that will make up
156
 *     the resulting blob.
157
 * @return {!Blob} The blob.
158
 */
159
goog.fs.getBlob = function(var_args) {
160
  var BlobBuilder = goog.global.BlobBuilder || goog.global.WebKitBlobBuilder;
161

162
  if (goog.isDef(BlobBuilder)) {
163
    var bb = new BlobBuilder();
164
    for (var i = 0; i < arguments.length; i++) {
165
      bb.append(arguments[i]);
166
    }
167
    return bb.getBlob();
168
  } else {
169
    return goog.fs.getBlobWithProperties(goog.array.toArray(arguments));
170
  }
171
};
172

173

174
/**
175
 * Creates a blob with the given properties.
176
 * See https://developer.mozilla.org/en-US/docs/Web/API/Blob for more details.
177
 *
178
 * @param {Array<string|!Blob>} parts The values that will make up the
179
 *     resulting blob.
180
 * @param {string=} opt_type The MIME type of the Blob.
181
 * @param {string=} opt_endings Specifies how strings containing newlines are to
182
 *     be written out.
183
 * @return {!Blob} The blob.
184
 */
185
goog.fs.getBlobWithProperties = function(parts, opt_type, opt_endings) {
186
  var BlobBuilder = goog.global.BlobBuilder || goog.global.WebKitBlobBuilder;
187

188
  if (goog.isDef(BlobBuilder)) {
189
    var bb = new BlobBuilder();
190
    for (var i = 0; i < parts.length; i++) {
191
      bb.append(parts[i], opt_endings);
192
    }
193
    return bb.getBlob(opt_type);
194
  } else if (goog.isDef(goog.global.Blob)) {
195
    var properties = {};
196
    if (opt_type) {
197
      properties['type'] = opt_type;
198
    }
199
    if (opt_endings) {
200
      properties['endings'] = opt_endings;
201
    }
202
    return new Blob(parts, properties);
203
  } else {
204
    throw Error('This browser doesn\'t seem to support creating Blobs');
205
  }
206
};
207

208

209
/**
210
 * Converts a Blob or a File into a string. This should only be used when the
211
 * blob is known to be small.
212
 *
213
 * @param {!Blob} blob The blob to convert.
214
 * @param {string=} opt_encoding The name of the encoding to use.
215
 * @return {!goog.async.Deferred} The deferred string. If an error occurrs, the
216
 *     errback is called with a {@link goog.fs.Error}.
217
 * @deprecated Use {@link goog.fs.FileReader.readAsText} instead.
218
 */
219
goog.fs.blobToString = function(blob, opt_encoding) {
220
  return goog.fs.FileReader.readAsText(blob, opt_encoding);
221
};
222

223

224
/**
225
 * Slices the blob. The returned blob contains data from the start byte
226
 * (inclusive) till the end byte (exclusive). Negative indices can be used
227
 * to count bytes from the end of the blob (-1 == blob.size - 1). Indices
228
 * are always clamped to blob range. If end is omitted, all the data till
229
 * the end of the blob is taken.
230
 *
231
 * @param {!Blob} blob The blob to be sliced.
232
 * @param {number} start Index of the starting byte.
233
 * @param {number=} opt_end Index of the ending byte.
234
 * @return {Blob} The blob slice or null if not supported.
235
 */
236
goog.fs.sliceBlob = function(blob, start, opt_end) {
237
  if (!goog.isDef(opt_end)) {
238
    opt_end = blob.size;
239
  }
240
  if (blob.webkitSlice) {
241
    // Natively accepts negative indices, clamping to the blob range and
242
    // range end is optional. See http://trac.webkit.org/changeset/83873
243
    return blob.webkitSlice(start, opt_end);
244
  } else if (blob.mozSlice) {
245
    // Natively accepts negative indices, clamping to the blob range and
246
    // range end is optional. See https://developer.mozilla.org/en/DOM/Blob
247
    // and http://hg.mozilla.org/mozilla-central/rev/dae833f4d934
248
    return blob.mozSlice(start, opt_end);
249
  } else if (blob.slice) {
250
    // Old versions of Firefox and Chrome use the original specification.
251
    // Negative indices are not accepted, only range end is clamped and
252
    // range end specification is obligatory.
253
    // See http://www.w3.org/TR/2009/WD-FileAPI-20091117/
254
    if ((goog.userAgent.GECKO && !goog.userAgent.isVersionOrHigher('13.0')) ||
255
        (goog.userAgent.WEBKIT && !goog.userAgent.isVersionOrHigher('537.1'))) {
256
      if (start < 0) {
257
        start += blob.size;
258
      }
259
      if (start < 0) {
260
        start = 0;
261
      }
262
      if (opt_end < 0) {
263
        opt_end += blob.size;
264
      }
265
      if (opt_end < start) {
266
        opt_end = start;
267
      }
268
      return blob.slice(start, opt_end - start);
269
    }
270
    // IE and the latest versions of Firefox and Chrome use the new
271
    // specification. Natively accepts negative indices, clamping to the blob
272
    // range and range end is optional.
273
    // See http://dev.w3.org/2006/webapi/FileAPI/
274
    return blob.slice(start, opt_end);
275
  }
276
  return null;
277
};
278

279