mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-06 09:05:45 +00:00
508 lines
21 KiB
JavaScript
508 lines
21 KiB
JavaScript
/* -*- indent-tabs-mode: nil; js-indent-level: 4 -*-
|
|
* vim: sw=4 ts=4 sts=4 et filetype=javascript
|
|
* This Source Code Form is subject to the terms of the Mozilla Public
|
|
* License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
|
|
|
|
this.EXPORTED_SYMBOLS = [
|
|
"NetUtil",
|
|
];
|
|
|
|
/**
|
|
* Necko utilities
|
|
*/
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
//// Constants
|
|
|
|
const Ci = Components.interfaces;
|
|
const Cc = Components.classes;
|
|
const Cr = Components.results;
|
|
const Cu = Components.utils;
|
|
|
|
const PR_UINT32_MAX = 0xffffffff;
|
|
|
|
Components.utils.import("resource://gre/modules/XPCOMUtils.jsm");
|
|
Components.utils.import("resource://gre/modules/Services.jsm");
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
//// NetUtil Object
|
|
|
|
this.NetUtil = {
|
|
/**
|
|
* Function to perform simple async copying from aSource (an input stream)
|
|
* to aSink (an output stream). The copy will happen on some background
|
|
* thread. Both streams will be closed when the copy completes.
|
|
*
|
|
* @param aSource
|
|
* The input stream to read from
|
|
* @param aSink
|
|
* The output stream to write to
|
|
* @param aCallback [optional]
|
|
* A function that will be called at copy completion with a single
|
|
* argument: the nsresult status code for the copy operation.
|
|
*
|
|
* @return An nsIRequest representing the copy operation (for example, this
|
|
* can be used to cancel the copying). The consumer can ignore the
|
|
* return value if desired.
|
|
*/
|
|
asyncCopy: function NetUtil_asyncCopy(aSource, aSink,
|
|
aCallback = null)
|
|
{
|
|
if (!aSource || !aSink) {
|
|
let exception = new Components.Exception(
|
|
"Must have a source and a sink",
|
|
Cr.NS_ERROR_INVALID_ARG,
|
|
Components.stack.caller
|
|
);
|
|
throw exception;
|
|
}
|
|
|
|
// make a stream copier
|
|
var copier = Cc["@mozilla.org/network/async-stream-copier;1"].
|
|
createInstance(Ci.nsIAsyncStreamCopier2);
|
|
copier.init(aSource, aSink,
|
|
null /* Default event target */,
|
|
0 /* Default length */,
|
|
true, true /* Auto-close */);
|
|
|
|
var observer;
|
|
if (aCallback) {
|
|
observer = {
|
|
onStartRequest: function(aRequest, aContext) {},
|
|
onStopRequest: function(aRequest, aContext, aStatusCode) {
|
|
aCallback(aStatusCode);
|
|
}
|
|
}
|
|
} else {
|
|
observer = null;
|
|
}
|
|
|
|
// start the copying
|
|
copier.QueryInterface(Ci.nsIAsyncStreamCopier).asyncCopy(observer, null);
|
|
return copier;
|
|
},
|
|
|
|
/**
|
|
* Asynchronously opens a source and fetches the response. While the fetch
|
|
* is asynchronous, I/O may happen on the main thread. When reading from
|
|
* a local file, prefer using "OS.File" methods instead.
|
|
*
|
|
* @param aSource
|
|
* This argument can be one of the following:
|
|
* - An options object that will be passed to NetUtil.newChannel.
|
|
* - An existing nsIChannel.
|
|
* - An existing nsIInputStream.
|
|
* Using an nsIURI, nsIFile, or string spec directly is deprecated.
|
|
* @param aCallback
|
|
* The callback function that will be notified upon completion. It
|
|
* will get these arguments:
|
|
* 1) An nsIInputStream containing the data from aSource, if any.
|
|
* 2) The status code from opening the source.
|
|
* 3) Reference to the nsIRequest.
|
|
*/
|
|
asyncFetch: function NetUtil_asyncFetch(aSource, aCallback)
|
|
{
|
|
if (!aSource || !aCallback) {
|
|
let exception = new Components.Exception(
|
|
"Must have a source and a callback",
|
|
Cr.NS_ERROR_INVALID_ARG,
|
|
Components.stack.caller
|
|
);
|
|
throw exception;
|
|
}
|
|
|
|
// Create a pipe that will create our output stream that we can use once
|
|
// we have gotten all the data.
|
|
let pipe = Cc["@mozilla.org/pipe;1"].
|
|
createInstance(Ci.nsIPipe);
|
|
pipe.init(true, true, 0, PR_UINT32_MAX, null);
|
|
|
|
// Create a listener that will give data to the pipe's output stream.
|
|
let listener = Cc["@mozilla.org/network/simple-stream-listener;1"].
|
|
createInstance(Ci.nsISimpleStreamListener);
|
|
listener.init(pipe.outputStream, {
|
|
onStartRequest: function(aRequest, aContext) {},
|
|
onStopRequest: function(aRequest, aContext, aStatusCode) {
|
|
pipe.outputStream.close();
|
|
aCallback(pipe.inputStream, aStatusCode, aRequest);
|
|
}
|
|
});
|
|
|
|
// Input streams are handled slightly differently from everything else.
|
|
if (aSource instanceof Ci.nsIInputStream) {
|
|
let pump = Cc["@mozilla.org/network/input-stream-pump;1"].
|
|
createInstance(Ci.nsIInputStreamPump);
|
|
pump.init(aSource, -1, -1, 0, 0, true);
|
|
pump.asyncRead(listener, null);
|
|
return;
|
|
}
|
|
|
|
let channel = aSource;
|
|
if (!(channel instanceof Ci.nsIChannel)) {
|
|
channel = this.newChannel(aSource);
|
|
}
|
|
|
|
try {
|
|
// Open the channel using asyncOpen2() if the loadinfo contains one
|
|
// of the security mode flags, otherwise fall back to use asyncOpen().
|
|
if (channel.loadInfo &&
|
|
channel.loadInfo.securityMode != 0) {
|
|
channel.asyncOpen2(listener);
|
|
}
|
|
else {
|
|
// Log deprecation warning to console to make sure all channels
|
|
// are created providing the correct security flags in the loadinfo.
|
|
// See nsILoadInfo for all available security flags and also the API
|
|
// of NetUtil.newChannel() for details above.
|
|
Cu.reportError("NetUtil.jsm: asyncFetch() requires the channel to have " +
|
|
"one of the security flags set in the loadinfo (see nsILoadInfo). " +
|
|
"Please create channel using NetUtil.newChannel()");
|
|
channel.asyncOpen(listener, null);
|
|
}
|
|
}
|
|
catch (e) {
|
|
let exception = new Components.Exception(
|
|
"Failed to open input source '" + channel.originalURI.spec + "'",
|
|
e.result,
|
|
Components.stack.caller,
|
|
aSource,
|
|
e
|
|
);
|
|
throw exception;
|
|
}
|
|
},
|
|
|
|
/**
|
|
* Constructs a new URI for the given spec, character set, and base URI, or
|
|
* an nsIFile.
|
|
*
|
|
* @param aTarget
|
|
* The string spec for the desired URI or an nsIFile.
|
|
* @param aOriginCharset [optional]
|
|
* The character set for the URI. Only used if aTarget is not an
|
|
* nsIFile.
|
|
* @param aBaseURI [optional]
|
|
* The base URI for the spec. Only used if aTarget is not an
|
|
* nsIFile.
|
|
*
|
|
* @return an nsIURI object.
|
|
*/
|
|
newURI: function NetUtil_newURI(aTarget, aOriginCharset, aBaseURI)
|
|
{
|
|
if (!aTarget) {
|
|
let exception = new Components.Exception(
|
|
"Must have a non-null string spec or nsIFile object",
|
|
Cr.NS_ERROR_INVALID_ARG,
|
|
Components.stack.caller
|
|
);
|
|
throw exception;
|
|
}
|
|
|
|
if (aTarget instanceof Ci.nsIFile) {
|
|
return this.ioService.newFileURI(aTarget);
|
|
}
|
|
|
|
return this.ioService.newURI(aTarget, aOriginCharset, aBaseURI);
|
|
},
|
|
|
|
/**
|
|
* Constructs a new channel for the given source.
|
|
*
|
|
* Keep in mind that URIs coming from a webpage should *never* use the
|
|
* systemPrincipal as the loadingPrincipal.
|
|
*
|
|
* @param aWhatToLoad
|
|
* This argument used to be a string spec for the desired URI, an
|
|
* nsIURI, or an nsIFile. Now it should be an options object with
|
|
* the following properties:
|
|
* {
|
|
* uri:
|
|
* The full URI spec string, nsIURI or nsIFile to create the
|
|
* channel for.
|
|
* Note that this cannot be an nsIFile if you have to specify a
|
|
* non-default charset or base URI. Call NetUtil.newURI first if
|
|
* you need to construct an URI using those options.
|
|
* loadingNode:
|
|
* The loadingDocument of the channel.
|
|
* The element or document where the result of this request will
|
|
* be used. This is the document/element that will get access to
|
|
* the result of this request. For example for an image load,
|
|
* it's the document in which the image will be loaded. And for
|
|
* a CSS stylesheet it's the document whose rendering will be
|
|
* affected by the stylesheet.
|
|
* If possible, pass in the element which is performing the load.
|
|
* But if the load is coming from a JS API (such as
|
|
* XMLHttpRequest) or if the load might be coalesced across
|
|
* multiple elements (such as for <img>) then pass in the
|
|
* Document node instead.
|
|
* For loads that are not related to any document, such as loads
|
|
* coming from addons or internal browser features, omit this
|
|
* property and specify a loadingPrincipal or
|
|
* loadUsingSystemPrincipal instead.
|
|
* loadingPrincipal:
|
|
* The loadingPrincipal of the channel.
|
|
* The principal of the document where the result of this request
|
|
* will be used.
|
|
* This defaults to the principal of aLoadingNode, so when
|
|
* aLoadingNode is passed this can be left as null. However for
|
|
* loads where aLoadingNode is null this argument must be passed.
|
|
* For example for loads from a WebWorker, pass the principal of
|
|
* that worker. For loads from an addon or from internal browser
|
|
* features, pass the system principal.
|
|
* This principal should almost always be the system principal if
|
|
* loadingNode is omitted, in which case you can use the
|
|
* useSystemPrincipal property. The only exception to this is
|
|
* for loads from WebWorkers since they don't have any nodes to
|
|
* be passed as loadingNode.
|
|
* Please note, loadingPrincipal is *not* the principal of the
|
|
* resource being loaded, but rather the principal of the context
|
|
* where the resource will be used.
|
|
* loadUsingSystemPrincipal:
|
|
* Set this to true to use the system principal as
|
|
* loadingPrincipal. This must be omitted if loadingPrincipal or
|
|
* loadingNode are present.
|
|
* This should be used with care as it skips security checks.
|
|
* triggeringPrincipal:
|
|
* The triggeringPrincipal of the load.
|
|
* The triggeringPrincipal is the principal of the resource that
|
|
* caused this particular URL to be loaded.
|
|
* Most likely the triggeringPrincipal and the loadingPrincipal
|
|
* are identical, in which case the triggeringPrincipal can be
|
|
* left out. In some cases the loadingPrincipal and the
|
|
* triggeringPrincipal are different however, e.g. a stylesheet
|
|
* may import a subresource. In that case the principal of the
|
|
* stylesheet which contains the import command is the
|
|
* triggeringPrincipal, and the principal of the document whose
|
|
* rendering is affected is the loadingPrincipal.
|
|
* securityFlags:
|
|
* The securityFlags of the channel.
|
|
* Any of the securityflags defined in nsILoadInfo.idl.
|
|
* contentPolicyType:
|
|
* The contentPolicyType of the channel.
|
|
* Any of the content types defined in nsIContentPolicy.idl.
|
|
* }
|
|
* @param aOriginCharset [deprecated]
|
|
* The character set for the URI. Only used if aWhatToLoad is a
|
|
* string, which is a deprecated API. Must be undefined otherwise.
|
|
* Use NetUtil.newURI if you need to use this option.
|
|
* @param aBaseURI [deprecated]
|
|
* The base URI for the spec. Only used if aWhatToLoad is a string,
|
|
* which is a deprecated API. Must be undefined otherwise. Use
|
|
* NetUtil.newURI if you need to use this option.
|
|
* @return an nsIChannel object.
|
|
*/
|
|
newChannel: function NetUtil_newChannel(aWhatToLoad, aOriginCharset, aBaseURI)
|
|
{
|
|
// Check for the deprecated API first.
|
|
if (typeof aWhatToLoad == "string" ||
|
|
(aWhatToLoad instanceof Ci.nsIFile) ||
|
|
(aWhatToLoad instanceof Ci.nsIURI)) {
|
|
|
|
let uri = (aWhatToLoad instanceof Ci.nsIURI)
|
|
? aWhatToLoad
|
|
: this.newURI(aWhatToLoad, aOriginCharset, aBaseURI);
|
|
|
|
// log deprecation warning for developers.
|
|
Services.console.logStringMessage(
|
|
"Warning: NetUtil.newChannel(uri) deprecated, please provide argument 'aWhatToLoad'");
|
|
|
|
// Provide default loadinfo arguments and call the new API.
|
|
let systemPrincipal =
|
|
Services.scriptSecurityManager.getSystemPrincipal();
|
|
|
|
return this.ioService.newChannelFromURI2(
|
|
uri,
|
|
null, // loadingNode
|
|
systemPrincipal, // loadingPrincipal
|
|
null, // triggeringPrincipal
|
|
Ci.nsILoadInfo.SEC_ALLOW_CROSS_ORIGIN_DATA_IS_NULL,
|
|
Ci.nsIContentPolicy.TYPE_OTHER);
|
|
}
|
|
|
|
// We are using the updated API, that requires only the options object.
|
|
if (typeof aWhatToLoad != "object" ||
|
|
aOriginCharset !== undefined ||
|
|
aBaseURI !== undefined) {
|
|
throw new Components.Exception(
|
|
"newChannel requires a single object argument",
|
|
Cr.NS_ERROR_INVALID_ARG,
|
|
Components.stack.caller
|
|
);
|
|
}
|
|
|
|
let { uri,
|
|
loadingNode,
|
|
loadingPrincipal,
|
|
loadUsingSystemPrincipal,
|
|
triggeringPrincipal,
|
|
securityFlags,
|
|
contentPolicyType } = aWhatToLoad;
|
|
|
|
if (!uri) {
|
|
throw new Components.Exception(
|
|
"newChannel requires the 'uri' property on the options object.",
|
|
Cr.NS_ERROR_INVALID_ARG,
|
|
Components.stack.caller
|
|
);
|
|
}
|
|
|
|
if (typeof uri == "string" || uri instanceof Ci.nsIFile) {
|
|
uri = this.newURI(uri);
|
|
}
|
|
|
|
if (!loadingNode && !loadingPrincipal && !loadUsingSystemPrincipal) {
|
|
throw new Components.Exception(
|
|
"newChannel requires at least one of the 'loadingNode'," +
|
|
" 'loadingPrincipal', or 'loadUsingSystemPrincipal'" +
|
|
" properties on the options object.",
|
|
Cr.NS_ERROR_INVALID_ARG,
|
|
Components.stack.caller
|
|
);
|
|
}
|
|
|
|
if (loadUsingSystemPrincipal === true) {
|
|
if (loadingNode || loadingPrincipal) {
|
|
throw new Components.Exception(
|
|
"newChannel does not accept 'loadUsingSystemPrincipal'" +
|
|
" if the 'loadingNode' or 'loadingPrincipal' properties" +
|
|
" are present on the options object.",
|
|
Cr.NS_ERROR_INVALID_ARG,
|
|
Components.stack.caller
|
|
);
|
|
}
|
|
loadingPrincipal = Services.scriptSecurityManager
|
|
.getSystemPrincipal();
|
|
} else if (loadUsingSystemPrincipal !== undefined) {
|
|
throw new Components.Exception(
|
|
"newChannel requires the 'loadUsingSystemPrincipal'" +
|
|
" property on the options object to be 'true' or 'undefined'.",
|
|
Cr.NS_ERROR_INVALID_ARG,
|
|
Components.stack.caller
|
|
);
|
|
}
|
|
|
|
if (securityFlags === undefined) {
|
|
securityFlags = loadUsingSystemPrincipal
|
|
? Ci.nsILoadInfo.SEC_ALLOW_CROSS_ORIGIN_DATA_IS_NULL
|
|
: Ci.nsILoadInfo.SEC_NORMAL;
|
|
}
|
|
|
|
if (contentPolicyType === undefined) {
|
|
if (!loadUsingSystemPrincipal) {
|
|
throw new Components.Exception(
|
|
"newChannel requires the 'contentPolicyType' property on" +
|
|
" the options object unless loading from system principal.",
|
|
Cr.NS_ERROR_INVALID_ARG,
|
|
Components.stack.caller
|
|
);
|
|
}
|
|
contentPolicyType = Ci.nsIContentPolicy.TYPE_OTHER;
|
|
}
|
|
|
|
return this.ioService.newChannelFromURI2(uri,
|
|
loadingNode || null,
|
|
loadingPrincipal || null,
|
|
triggeringPrincipal || null,
|
|
securityFlags,
|
|
contentPolicyType);
|
|
},
|
|
|
|
/**
|
|
* Reads aCount bytes from aInputStream into a string.
|
|
*
|
|
* @param aInputStream
|
|
* The input stream to read from.
|
|
* @param aCount
|
|
* The number of bytes to read from the stream.
|
|
* @param aOptions [optional]
|
|
* charset
|
|
* The character encoding of stream data.
|
|
* replacement
|
|
* The character to replace unknown byte sequences.
|
|
* If unset, it causes an exceptions to be thrown.
|
|
*
|
|
* @return the bytes from the input stream in string form.
|
|
*
|
|
* @throws NS_ERROR_INVALID_ARG if aInputStream is not an nsIInputStream.
|
|
* @throws NS_BASE_STREAM_WOULD_BLOCK if reading from aInputStream would
|
|
* block the calling thread (non-blocking mode only).
|
|
* @throws NS_ERROR_FAILURE if there are not enough bytes available to read
|
|
* aCount amount of data.
|
|
* @throws NS_ERROR_ILLEGAL_INPUT if aInputStream has invalid sequences
|
|
*/
|
|
readInputStreamToString: function NetUtil_readInputStreamToString(aInputStream,
|
|
aCount,
|
|
aOptions)
|
|
{
|
|
if (!(aInputStream instanceof Ci.nsIInputStream)) {
|
|
let exception = new Components.Exception(
|
|
"First argument should be an nsIInputStream",
|
|
Cr.NS_ERROR_INVALID_ARG,
|
|
Components.stack.caller
|
|
);
|
|
throw exception;
|
|
}
|
|
|
|
if (!aCount) {
|
|
let exception = new Components.Exception(
|
|
"Non-zero amount of bytes must be specified",
|
|
Cr.NS_ERROR_INVALID_ARG,
|
|
Components.stack.caller
|
|
);
|
|
throw exception;
|
|
}
|
|
|
|
if (aOptions && "charset" in aOptions) {
|
|
let cis = Cc["@mozilla.org/intl/converter-input-stream;1"].
|
|
createInstance(Ci.nsIConverterInputStream);
|
|
try {
|
|
// When replacement is set, the character that is unknown sequence
|
|
// replaces with aOptions.replacement character.
|
|
if (!("replacement" in aOptions)) {
|
|
// aOptions.replacement isn't set.
|
|
// If input stream has unknown sequences for aOptions.charset,
|
|
// throw NS_ERROR_ILLEGAL_INPUT.
|
|
aOptions.replacement = 0;
|
|
}
|
|
|
|
cis.init(aInputStream, aOptions.charset, aCount,
|
|
aOptions.replacement);
|
|
let str = {};
|
|
cis.readString(-1, str);
|
|
cis.close();
|
|
return str.value;
|
|
}
|
|
catch (e) {
|
|
// Adjust the stack so it throws at the caller's location.
|
|
throw new Components.Exception(e.message, e.result,
|
|
Components.stack.caller, e.data);
|
|
}
|
|
}
|
|
|
|
let sis = Cc["@mozilla.org/scriptableinputstream;1"].
|
|
createInstance(Ci.nsIScriptableInputStream);
|
|
sis.init(aInputStream);
|
|
try {
|
|
return sis.readBytes(aCount);
|
|
}
|
|
catch (e) {
|
|
// Adjust the stack so it throws at the caller's location.
|
|
throw new Components.Exception(e.message, e.result,
|
|
Components.stack.caller, e.data);
|
|
}
|
|
},
|
|
|
|
/**
|
|
* Returns a reference to nsIIOService.
|
|
*
|
|
* @return a reference to nsIIOService.
|
|
*/
|
|
get ioService()
|
|
{
|
|
delete this.ioService;
|
|
return this.ioService = Cc["@mozilla.org/network/io-service;1"].
|
|
getService(Ci.nsIIOService);
|
|
},
|
|
};
|