lib/goog/fs/url.js

1// Copyright 2015 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 Wrapper for URL and its createObjectUrl and revokeObjectUrl
17 * methods that are part of the HTML5 File API.
18 */
19
20goog.provide('goog.fs.url');
21
22
23/**
24 * Creates a blob URL for a blob object.
25 * Throws an error if the browser does not support Object Urls.
26 *
27 * @param {!Blob} blob The object for which to create the URL.
28 * @return {string} The URL for the object.
29 */
30goog.fs.url.createObjectUrl = function(blob) {
31 return goog.fs.url.getUrlObject_().createObjectURL(blob);
32};
33
34
35/**
36 * Revokes a URL created by {@link goog.fs.url.createObjectUrl}.
37 * Throws an error if the browser does not support Object Urls.
38 *
39 * @param {string} url The URL to revoke.
40 */
41goog.fs.url.revokeObjectUrl = function(url) {
42 goog.fs.url.getUrlObject_().revokeObjectURL(url);
43};
44
45
46/**
47 * @typedef {{createObjectURL: (function(!Blob): string),
48 * revokeObjectURL: function(string): void}}
49 */
50goog.fs.url.UrlObject_;
51
52
53/**
54 * Get the object that has the createObjectURL and revokeObjectURL functions for
55 * this browser.
56 *
57 * @return {goog.fs.url.UrlObject_} The object for this browser.
58 * @private
59 */
60goog.fs.url.getUrlObject_ = function() {
61 var urlObject = goog.fs.url.findUrlObject_();
62 if (urlObject != null) {
63 return urlObject;
64 } else {
65 throw Error('This browser doesn\'t seem to support blob URLs');
66 }
67};
68
69
70/**
71 * Finds the object that has the createObjectURL and revokeObjectURL functions
72 * for this browser.
73 *
74 * @return {?goog.fs.url.UrlObject_} The object for this browser or null if the
75 * browser does not support Object Urls.
76 * @suppress {unnecessaryCasts} Depending on how the code is compiled, casting
77 * goog.global to UrlObject_ may result in unnecessary cast warning.
78 * However, the cast cannot be removed because with different set of
79 * compiler flags, the cast is indeed necessary. As such, silencing it.
80 * @private
81 */
82goog.fs.url.findUrlObject_ = function() {
83 // This is what the spec says to do
84 // http://dev.w3.org/2006/webapi/FileAPI/#dfn-createObjectURL
85 if (goog.isDef(goog.global.URL) &&
86 goog.isDef(goog.global.URL.createObjectURL)) {
87 return /** @type {goog.fs.url.UrlObject_} */ (goog.global.URL);
88 // This is what Chrome does (as of 10.0.648.6 dev)
89 } else if (goog.isDef(goog.global.webkitURL) &&
90 goog.isDef(goog.global.webkitURL.createObjectURL)) {
91 return /** @type {goog.fs.url.UrlObject_} */ (goog.global.webkitURL);
92 // This is what the spec used to say to do
93 } else if (goog.isDef(goog.global.createObjectURL)) {
94 return /** @type {goog.fs.url.UrlObject_} */ (goog.global);
95 } else {
96 return null;
97 }
98};
99
100
101/**
102 * Checks whether this browser supports Object Urls. If not, calls to
103 * createObjectUrl and revokeObjectUrl will result in an error.
104 *
105 * @return {boolean} True if this browser supports Object Urls.
106 */
107goog.fs.url.browserSupportsObjectUrls = function() {
108 return goog.fs.url.findUrlObject_() != null;
109};