NetUtil.jsm

  • Revision slug: JavaScript_code_modules/NetUtil.jsm
  • Revision title: NetUtil.jsm
  • Revision id: 45646
  • Created:
  • Creator: sdwilsh
  • Is current revision? No
  • Comment 37 words added

Revision Content

{{ fx_minversion_header("3.6") }}

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

{{ interface("nsIAsyncStreamCopier") }} asyncCopy(aSource, aSink, aCallback)
{{ interface("nsIURI") }} newURI(aSpec, [optional] aOriginCharset, [optional] aBaseURI) {{ gecko_minversion_inline("1.9.3") }}

Methods

asyncCopy

The asyncCopy() method performs a simple asynchronous copy of data from a source input stream to a destination input 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 {{ interface("nsIInputStream") }} based object.
aSink
The output stream to which to copy the data. This must be an {{ interface("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 {{ interface("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!
  }
})

See also

Revision Source

<p>{{ fx_minversion_header("3.6") }}</p>
<p>The <code>NetUtil.jsm</code> JavaScript code module provides easy-to-use APIs for performing common network related tasks.</p>
<p>To use these utilities, you first need to import the code module into your JavaScript scope:</p>
<pre class="eval"><span class="nowiki">Components.utils.import("</span><a class=" external" href="resource://gre/modules/XPCOMUtils.jsm" rel="external nofollow" target="_blank" title="resource://gre/modules/XPCOMUtils.jsm"><span class="nowiki">resource://gre/modules/NetUtil.jsm</span></a><span class="nowiki">");</span>
</pre>
<p>Once you've imported the module, you can then use its methods.</p>
<h2 name="Method_overview">Method overview</h2>
<table class="standard-table"> <tbody> <tr> <td><code>{{ interface("nsIAsyncStreamCopier") }} asyncCopy(aSource, aSink, aCallback)</code></td> </tr> <tr> <td><code>{{ interface("nsIURI") }} newURI(aSpec, [optional] aOriginCharset, [optional] aBaseURI)</code> {{ gecko_minversion_inline("1.9.3") }}</td> </tr> </tbody>
</table><h2>Methods</h2>
<h3>asyncCopy</h3>
<p>The <code>asyncCopy()</code> method performs a simple asynchronous copy of data from a source input stream to a destination input stream. Both streams are automatically closed when the copy operation is completed.</p>
<pre>nsIAsyncStreamCopier asyncCopy(
  aSource,
  aSink,
  aCallback
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>aSource</code></dt> <dd>The input stream from which to read the source data. This must be an {{ interface("nsIInputStream") }} based object.</dd> <dt><code>aSink</code></dt> <dd>The output stream to which to copy the data. This must be an {{ interface("nsIOutputStream") }} based object.</dd> <dt><code>aCallback</code></dt> <dd>An optional function that will be called when the copy operation is completed. The callback receives a single parameter: the <code>nsresult</code> status code for the copy operation.</dd>
</dl>
<h6>Return value</h6>
<p>Returns the {{ interface("nsIAsyncStreamCopier") }} object that is handling the copy.</p>
<h6>Exceptions thrown</h6>
<p>This method throws an exception with the message "Must have a source and a sink" if either <code>aSource</code> or <code>aSink</code> is null.</p>
<h2>Example</h2>
<p>This example writes a string to a file; it comes from the test suite for the NetUtil module.</p>
<pre>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!
  }
})
</pre>
<h2>See also</h2>
<ul> <li><a class="internal" href="/en/JavaScript_code_modules/Using_JavaScript_code_modules" title="en/JavaScript code modules/Using JavaScript code modules">Using JavaScript code modules</a></li> <li><a class="internal" href="/en/JavaScript_code_modules" title="en/JavaScript code modules">JavaScript code modules</a></li> <li><a class="internal" href="/en/Components.utils.import" title="en/Components.utils.import"><code>Components.utils.import</code></a></li>
</ul>
Revert to this revision