NetUtil.jsm

The NetUtil.jsm JavaScript code module provides easy-to-use APIs for performing common network related tasks.

To use these utilities, you first need to import the code module into your JavaScript scope:

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

Once you've imported the module, you can then use its methods.

Method overview

Attributes

Methods

asyncCopy()

The asyncCopy() method performs a simple asynchronous copy of data from a source input stream to a destination output stream. Both streams are automatically closed when the copy operation is completed.

nsIAsyncStreamCopier asyncCopy(
  aSource,
  aSink,
  aCallback
); 

Parameters

aSource

The input stream from which to read the source data. This must be an nsIInputStream based object.

aSink

The output stream to which to copy the data. This must be an nsIOutputStream based object.

aCallback

An optional function that will be called when the copy operation is completed. The callback receives a single parameter: the nsresult status code for the copy operation.

Return value

Returns the nsIAsyncStreamCopier object that is handling the copy.

Exceptions thrown

This method throws an exception with the message "Must have a source and a sink" if either aSource or aSink is null.

Example

This example writes a string to a file; it comes from the test suite for the NetUtil module.

var file = Cc["@mozilla.org/file/directory_service;1"].
           getService(Ci.nsIProperties).
           get("TmpD", Ci.nsIFile);
file.append("test-file.tmp");
file.createUnique(Ci.nsIFile.NORMAL_FILE_TYPE, 0666);

// Then, we need an output stream to our output file.
var ostream = Cc["@mozilla.org/network/file-output-stream;1"].
              createInstance(Ci.nsIFileOutputStream);
ostream.init(file, -1, -1, 0);

// Finally, we need an input stream to take data from.
const TEST_DATA = "this is a test string";
let istream = Cc["@mozilla.org/io/string-input-stream;1"].
              createInstance(Ci.nsIStringInputStream);
istream.setData(TEST_DATA, TEST_DATA.length);

NetUtil.asyncCopy(istream, ostream, function(aResult) {
  if (!Components.isSuccessCode(aResult)) {
    // an error occurred!
  }
})

asyncFetch()

The asyncFetch() method opens an input source, asynchronously, and gives an nsIInputStream containing the data obtained to the callback provided. The callback may then consume data from the input stream passed to the callback.

asyncFetch(
  aSource,
  aCallback
); 

Parameters

aSource

The source to open asynchronously. This may be specified as an nsIURI, nsIFile, nsIChannel, nsIInputStream or as a string specifying the URL to open.

aCallback

A function that will be called when the open operation is completed. The callback receives three parameters: the input stream containing the data, if any (implementing nsIInputStream), an nsresult status code for the open operation, and a reference to the nsIRequest object.

Exceptions thrown

This method throws an exception with the message "Must have a source and a callback" if either aSource or aCallback is null.

Example

This example shows the basic code consumers would need to implement to be correct.

NetUtil.asyncFetch(channel, function(aInputStream, aResult) {
  // Check that we had success.
  if (!Components.isSuccessCode(aResult)) {
    // Handle error
    return;
  }

  // Consume the input stream.
});

Remarks

Creates a new channel for the specified URI string, nsIURI, or nsIFile.

nsIChannel newChannel(
  aWhatToLoad,
  [optional] aOriginCharset,
  [optional] aBaseURI
); 

Parameters

Return value

An nsIChannel allowing access to the specified data source.

aWhatToLoad

A string specifying a URI, or an nsIURI or nsIFile object. The returned method will allow access to the specified data.

aOriginCharset

The optional character set to use when interpreting aWhatToLoad as a string; this is ignored if aWhatToLoad is not a string. Defaults to UTF-8 if not provided.

aBaseURI

The base URI for the spec, specified as an nsIURI. Only used if aWhatToLoad is a string.

newURI()

The newURI() method creates a new nsIURI. This method wraps the nsIIOService.newURI().

nsIURI newURI(
  aTarget,
  [optional] aOriginCharset,
  [optional] aBaseURI
); 

Parameters

aTarget

Specifies the target of the URI as either a URI string or (starting in Gecko 2.0) as an nsIFile.

aOriginCharset

The optional character set for the URI. Defaults to UTF-8 if not provided.

aBaseURI

The base URI for the spec, specified as an nsIURI.

Return value

Returns the nsIURI object representing the specified target.

Exceptions thrown

This method throws an exception with the message "Must have a non-null string spec or nsIFile object" and result code NS_ERROR_INVALID_ARG if aSpec is null.

Reads a given number of bytes from an input stream, returning a string containing those bytes. This works even if some of those bytes are zeros, instead of terminating the string at the first zero byte.

String readInputStreamToString(
  aInputStream,
  aCount,
  aOptions
);

Parameters

aInputStream

The input stream from which to read the data.

aCount

The number of bytes to read from the stream. You can call nsIInputStream.available() to get the number of bytes currently available.

aOptions

Specifies additional options to control the reading process. This is a JavaScript object with fields as specified in Options.

Options

The aOptions parameter is a JavaScript object which can have any or all of the following fields:

Return value

A string containing the bytes read from the input stream.

Exceptions thrown

NS_ERROR_INVALID_ARG

The specified stream is not an nsIInputStream.

NS_BASE_STREAM_WOULD_BLOCK

Reading from the specified stream would block the calling thread, and the stream is in non-blocking mode.

NS_ERROR_FAILURE

There aren't at least aCount bytes available to read from the stream.

NS_ERROR_ILLEGAL_INPUT

The input stream has invalid byte sequences, and no replacement character was specified using aOptions.replacement.

See also

• Using JavaScript code modules
• JavaScript code modules
• Components.utils.import