Skip to content

Commit

Permalink
Bug 1125618 - Revise NetUtil.jsm API for creating channels and fetchi…
Browse files Browse the repository at this point in the history 
…ng data while providing load info. r=sicking
  • Loading branch information
Paolo Amadini committed Feb 11, 2015
1 parent 6153d7b commit 50cc056
Show file tree
Hide file tree
Showing 2 changed files with 287 additions and 178 deletions.
308 changes: 184 additions & 124 deletions netwerk/base/NetUtil.jsm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,9 @@ 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

Expand Down Expand Up @@ -81,22 +84,24 @@ this.NetUtil = {
},

/**
* Asynchronously opens a source and fetches the response. A source can be
* an nsIURI, nsIFile, string spec, nsIChannel, or nsIInputStream. The
* provided callback will get an input stream containing the response, the
* result code, and a reference to the request.
* 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
* The nsIURI, nsIFile, string spec, nsIChannel, or nsIInputStream
* to open.
* 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 two arguments:
* 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_asyncOpen(aSource, aCallback)
asyncFetch: function NetUtil_asyncFetch(aSource, aCallback)
{
if (!aSource || !aCallback) {
let exception = new Components.Exception(
Expand Down Expand Up @@ -154,31 +159,7 @@ this.NetUtil = {
},

/**
* Asynchronously opens a source and fetches the response. A source can be
* an nsIURI, nsIFile, string spec, nsIChannel, or nsIInputStream. The
* provided callback will get an input stream containing the response, the
* result code, and a reference to the request.
*
* Please note, if aSource is an instance of an nsIChannel, then
* aLoadingNode, aLoadingPrincipal, aTriggeringPrincipal, aSecurityFlags,
* aContentPolicyType must be "undefined".
*
* @param aSource
* The nsIURI, nsIFile, string spec, nsIChannel, or nsIInputStream
* to open.
* @param aCallback
* The callback function that will be notified upon completion. It
* will get two arguments:
* 1) An nsIInputStream containing the data from aSource, if any.
* 2) The status code from opening the source.
* 3) Reference to the nsIRequest.
* @param aLoadingNode, aLoadingPrincipal, aTriggeringPrincipal
* aSecurityFlags, aContentPolicyType
* See param description in NetUtil_newChannel2.
*
* Note: As an interim we have asyncFetch as well as asyncFetch2.
* Once Bug 1087720 (which converts all js callers to use
* asyncFetch2) lands, we can remove asyncFetch completely.
* @deprecated Use asyncFecth({ ...options... }, callback) instead.
*/
asyncFetch2: function NetUtil_asyncFetch2(aSource,
aCallback,
Expand Down Expand Up @@ -303,106 +284,194 @@ this.NetUtil = {
},

/**
* Constructs a new channel for the given spec, character set, and base URI,
* or nsIURI, or nsIFile.
* 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
* The string spec for the desired URI, an nsIURI, or an nsIFile.
* @param aOriginCharset [optional]
* 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 or nsIURI to create the channel for.
* Note that this cannot be an nsIFile and you cannot 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 is generally the principal of the loadingNode. However
* for loads where loadingNode is omitted this argument still
* needs to 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.
* @param aBaseURI [optional]
* The base URI for the spec. Only used if aWhatToLoad is a string.
* 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)
{
if (!aWhatToLoad) {
let exception = new Components.Exception(
"Must have a non-null string spec, nsIURI, or nsIFile object",
// 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);

return this.ioService.newChannelFromURI(uri);
}

// 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
);
throw exception;
}

let uri = aWhatToLoad;
if (!(aWhatToLoad instanceof Ci.nsIURI)) {
// We either have a string or an nsIFile that we'll need a URI for.
uri = this.newURI(aWhatToLoad, aOriginCharset, aBaseURI);
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
);
}

return this.ioService.newChannelFromURI(uri);
if (typeof uri == "string") {
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 = 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);
},

/**
* Constructs a new channel for the given spec, character set, and base URI,
* or nsIURI, or nsIFile.
*
* @param aWhatToLoad
* The string spec for the desired URI, an nsIURI, or an nsIFile.
* @param aOriginCharset
* The character set for the URI. Only used if aWhatToLoad is a
* string.
* @param aBaseURI
* The base URI for the spec. Only used if aWhatToLoad is a string.
* @param aLoadingNode
* 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, use null here.
* @param aLoadingPrincipal
* The loadingPrincipal of the channel.
* The principal of the document where the result of this request will
* be used.
* This is generally the principal of the aLoadingNode. However for
* loads where aLoadingNode is null this argument still needs to 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
* aLoadingNode is null. The only exception to this is for loads
* from WebWorkers since they don't have any nodes to be passed as
* aLoadingNode.
* Please note, aLoadingPrincipal is *not* the principal of the
* resource being loaded. But rather the principal of the context
* where the resource will be used.
* @param aTriggeringPrincipal
* 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.
* @param aSecurityFlags
* The securityFlags of the channel.
* Any of the securityflags defined in nsILoadInfo.idl
* @param aContentPolicyType
* The contentPolicyType of the channel.
* Any of the content types defined in nsIContentPolicy.idl
* @return an nsIChannel object.
*
* Keep in mind that URIs coming from a webpage should *never* use the
* systemPrincipal as the loadingPrincipal.
*
* Note: As an interim we have newChannel as well as newChannel2.
* Once Bug 1087720 (which converts all js callers to use
* newChannel2) lands, we can remove newChannel completely.
* @deprecated Use newChannel({ ...options... }) instead.
*/
newChannel2: function NetUtil_newChannel2(aWhatToLoad,
aOriginCharset,
Expand Down Expand Up @@ -485,7 +554,7 @@ this.NetUtil = {
let cis = Cc["@mozilla.org/intl/converter-input-stream;1"].
createInstance(Ci.nsIConverterInputStream);
try {
// When replacement is set, the character that is unknown sequence
// When replacement is set, the character that is unknown sequence
// replaces with aOptions.replacement character.
if (!("replacement" in aOptions)) {
// aOptions.replacement isn't set.
Expand Down Expand Up @@ -533,12 +602,3 @@ this.NetUtil = {
getService(Ci.nsIIOService);
},
};

////////////////////////////////////////////////////////////////////////////////
//// Initialization

Components.utils.import("resource://gre/modules/XPCOMUtils.jsm");

// Define our lazy getters.
XPCOMUtils.defineLazyServiceGetter(this, "ioUtil", "@mozilla.org/io-util;1",
"nsIIOUtil");
Loading

0 comments on commit 50cc056

Please sign in to comment.