michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*-
michael@0:  * vim: sw=4 ts=4 sts=4 et filetype=javascript
michael@0:  * This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: this.EXPORTED_SYMBOLS = [
michael@0:   "NetUtil",
michael@0: ];
michael@0: 
michael@0: /**
michael@0:  * Necko utilities
michael@0:  */
michael@0: 
michael@0: ////////////////////////////////////////////////////////////////////////////////
michael@0: //// Constants
michael@0: 
michael@0: const Ci = Components.interfaces;
michael@0: const Cc = Components.classes;
michael@0: const Cr = Components.results;
michael@0: const Cu = Components.utils;
michael@0: 
michael@0: const PR_UINT32_MAX = 0xffffffff;
michael@0: 
michael@0: ////////////////////////////////////////////////////////////////////////////////
michael@0: //// NetUtil Object
michael@0: 
michael@0: this.NetUtil = {
michael@0:     /**
michael@0:      * Function to perform simple async copying from aSource (an input stream)
michael@0:      * to aSink (an output stream).  The copy will happen on some background
michael@0:      * thread.  Both streams will be closed when the copy completes.
michael@0:      *
michael@0:      * @param aSource
michael@0:      *        The input stream to read from
michael@0:      * @param aSink
michael@0:      *        The output stream to write to
michael@0:      * @param aCallback [optional]
michael@0:      *        A function that will be called at copy completion with a single
michael@0:      *        argument: the nsresult status code for the copy operation.
michael@0:      *
michael@0:      * @return An nsIRequest representing the copy operation (for example, this
michael@0:      *         can be used to cancel the copying).  The consumer can ignore the
michael@0:      *         return value if desired.
michael@0:      */
michael@0:     asyncCopy: function NetUtil_asyncCopy(aSource, aSink,
michael@0:                                           aCallback = null)
michael@0:     {
michael@0:         if (!aSource || !aSink) {
michael@0:             let exception = new Components.Exception(
michael@0:                 "Must have a source and a sink",
michael@0:                 Cr.NS_ERROR_INVALID_ARG,
michael@0:                 Components.stack.caller
michael@0:             );
michael@0:             throw exception;
michael@0:         }
michael@0: 
michael@0:         // make a stream copier
michael@0:         var copier = Cc["@mozilla.org/network/async-stream-copier;1"].
michael@0:             createInstance(Ci.nsIAsyncStreamCopier2);
michael@0:         copier.init(aSource, aSink,
michael@0:                     null /* Default event target */,
michael@0:                     0 /* Default length */,
michael@0:                     true, true /* Auto-close */);
michael@0: 
michael@0:         var observer;
michael@0:         if (aCallback) {
michael@0:             observer = {
michael@0:                 onStartRequest: function(aRequest, aContext) {},
michael@0:                 onStopRequest: function(aRequest, aContext, aStatusCode) {
michael@0:                     aCallback(aStatusCode);
michael@0:                 }
michael@0:             }
michael@0:         } else {
michael@0:             observer = null;
michael@0:         }
michael@0: 
michael@0:         // start the copying
michael@0:         copier.QueryInterface(Ci.nsIAsyncStreamCopier).asyncCopy(observer, null);
michael@0:         return copier;
michael@0:     },
michael@0: 
michael@0:     /**
michael@0:      * Asynchronously opens a source and fetches the response.  A source can be
michael@0:      * an nsIURI, nsIFile, string spec, nsIChannel, or nsIInputStream.  The
michael@0:      * provided callback will get an input stream containing the response, the
michael@0:      * result code, and a reference to the request.
michael@0:      *
michael@0:      * @param aSource
michael@0:      *        The nsIURI, nsIFile, string spec, nsIChannel, or nsIInputStream
michael@0:      *        to open.
michael@0:      * @param aCallback
michael@0:      *        The callback function that will be notified upon completion.  It
michael@0:      *        will get two arguments:
michael@0:      *        1) An nsIInputStream containing the data from aSource, if any.
michael@0:      *        2) The status code from opening the source.
michael@0:      *        3) Reference to the nsIRequest.
michael@0:      */
michael@0:     asyncFetch: function NetUtil_asyncOpen(aSource, aCallback)
michael@0:     {
michael@0:         if (!aSource || !aCallback) {
michael@0:             let exception = new Components.Exception(
michael@0:                 "Must have a source and a callback",
michael@0:                 Cr.NS_ERROR_INVALID_ARG,
michael@0:                 Components.stack.caller
michael@0:             );
michael@0:             throw exception;
michael@0:         }
michael@0: 
michael@0:         // Create a pipe that will create our output stream that we can use once
michael@0:         // we have gotten all the data.
michael@0:         let pipe = Cc["@mozilla.org/pipe;1"].
michael@0:                    createInstance(Ci.nsIPipe);
michael@0:         pipe.init(true, true, 0, PR_UINT32_MAX, null);
michael@0: 
michael@0:         // Create a listener that will give data to the pipe's output stream.
michael@0:         let listener = Cc["@mozilla.org/network/simple-stream-listener;1"].
michael@0:                        createInstance(Ci.nsISimpleStreamListener);
michael@0:         listener.init(pipe.outputStream, {
michael@0:             onStartRequest: function(aRequest, aContext) {},
michael@0:             onStopRequest: function(aRequest, aContext, aStatusCode) {
michael@0:                 pipe.outputStream.close();
michael@0:                 aCallback(pipe.inputStream, aStatusCode, aRequest);
michael@0:             }
michael@0:         });
michael@0: 
michael@0:         // Input streams are handled slightly differently from everything else.
michael@0:         if (aSource instanceof Ci.nsIInputStream) {
michael@0:             let pump = Cc["@mozilla.org/network/input-stream-pump;1"].
michael@0:                        createInstance(Ci.nsIInputStreamPump);
michael@0:             pump.init(aSource, -1, -1, 0, 0, true);
michael@0:             pump.asyncRead(listener, null);
michael@0:             return;
michael@0:         }
michael@0: 
michael@0:         let channel = aSource;
michael@0:         if (!(channel instanceof Ci.nsIChannel)) {
michael@0:             channel = this.newChannel(aSource);
michael@0:         }
michael@0: 
michael@0:         try {
michael@0:             channel.asyncOpen(listener, null);
michael@0:         }
michael@0:         catch (e) {
michael@0:             let exception = new Components.Exception(
michael@0:                 "Failed to open input source '" + channel.originalURI.spec + "'",
michael@0:                 e.result,
michael@0:                 Components.stack.caller,
michael@0:                 aSource,
michael@0:                 e
michael@0:             );
michael@0:             throw exception;
michael@0:         }
michael@0:     },
michael@0: 
michael@0:     /**
michael@0:      * Constructs a new URI for the given spec, character set, and base URI, or
michael@0:      * an nsIFile.
michael@0:      *
michael@0:      * @param aTarget
michael@0:      *        The string spec for the desired URI or an nsIFile.
michael@0:      * @param aOriginCharset [optional]
michael@0:      *        The character set for the URI.  Only used if aTarget is not an
michael@0:      *        nsIFile.
michael@0:      * @param aBaseURI [optional]
michael@0:      *        The base URI for the spec.  Only used if aTarget is not an
michael@0:      *        nsIFile.
michael@0:      *
michael@0:      * @return an nsIURI object.
michael@0:      */
michael@0:     newURI: function NetUtil_newURI(aTarget, aOriginCharset, aBaseURI)
michael@0:     {
michael@0:         if (!aTarget) {
michael@0:             let exception = new Components.Exception(
michael@0:                 "Must have a non-null string spec or nsIFile object",
michael@0:                 Cr.NS_ERROR_INVALID_ARG,
michael@0:                 Components.stack.caller
michael@0:             );
michael@0:             throw exception;
michael@0:         }
michael@0: 
michael@0:         if (aTarget instanceof Ci.nsIFile) {
michael@0:             return this.ioService.newFileURI(aTarget);
michael@0:         }
michael@0: 
michael@0:         return this.ioService.newURI(aTarget, aOriginCharset, aBaseURI);
michael@0:     },
michael@0: 
michael@0:     /**
michael@0:      * Constructs a new channel for the given spec, character set, and base URI,
michael@0:      * or nsIURI, or nsIFile.
michael@0:      *
michael@0:      * @param aWhatToLoad
michael@0:      *        The string spec for the desired URI, an nsIURI, or an nsIFile.
michael@0:      * @param aOriginCharset [optional]
michael@0:      *        The character set for the URI.  Only used if aWhatToLoad is a
michael@0:      *        string.
michael@0:      * @param aBaseURI [optional]
michael@0:      *        The base URI for the spec.  Only used if aWhatToLoad is a string.
michael@0:      *
michael@0:      * @return an nsIChannel object.
michael@0:      */
michael@0:     newChannel: function NetUtil_newChannel(aWhatToLoad, aOriginCharset,
michael@0:                                             aBaseURI)
michael@0:     {
michael@0:         if (!aWhatToLoad) {
michael@0:             let exception = new Components.Exception(
michael@0:                 "Must have a non-null string spec, nsIURI, or nsIFile object",
michael@0:                 Cr.NS_ERROR_INVALID_ARG,
michael@0:                 Components.stack.caller
michael@0:             );
michael@0:             throw exception;
michael@0:         }
michael@0: 
michael@0:         let uri = aWhatToLoad;
michael@0:         if (!(aWhatToLoad instanceof Ci.nsIURI)) {
michael@0:             // We either have a string or an nsIFile that we'll need a URI for.
michael@0:             uri = this.newURI(aWhatToLoad, aOriginCharset, aBaseURI);
michael@0:         }
michael@0: 
michael@0:         return this.ioService.newChannelFromURI(uri);
michael@0:     },
michael@0: 
michael@0:     /**
michael@0:      * Reads aCount bytes from aInputStream into a string.
michael@0:      *
michael@0:      * @param aInputStream
michael@0:      *        The input stream to read from.
michael@0:      * @param aCount
michael@0:      *        The number of bytes to read from the stream.
michael@0:      * @param aOptions [optional]
michael@0:      *        charset
michael@0:      *          The character encoding of stream data.
michael@0:      *        replacement
michael@0:      *          The character to replace unknown byte sequences.
michael@0:      *          If unset, it causes an exceptions to be thrown.
michael@0:      *
michael@0:      * @return the bytes from the input stream in string form.
michael@0:      *
michael@0:      * @throws NS_ERROR_INVALID_ARG if aInputStream is not an nsIInputStream.
michael@0:      * @throws NS_BASE_STREAM_WOULD_BLOCK if reading from aInputStream would
michael@0:      *         block the calling thread (non-blocking mode only).
michael@0:      * @throws NS_ERROR_FAILURE if there are not enough bytes available to read
michael@0:      *         aCount amount of data.
michael@0:      * @throws NS_ERROR_ILLEGAL_INPUT if aInputStream has invalid sequences
michael@0:      */
michael@0:     readInputStreamToString: function NetUtil_readInputStreamToString(aInputStream,
michael@0:                                                                       aCount,
michael@0:                                                                       aOptions)
michael@0:     {
michael@0:         if (!(aInputStream instanceof Ci.nsIInputStream)) {
michael@0:             let exception = new Components.Exception(
michael@0:                 "First argument should be an nsIInputStream",
michael@0:                 Cr.NS_ERROR_INVALID_ARG,
michael@0:                 Components.stack.caller
michael@0:             );
michael@0:             throw exception;
michael@0:         }
michael@0: 
michael@0:         if (!aCount) {
michael@0:             let exception = new Components.Exception(
michael@0:                 "Non-zero amount of bytes must be specified",
michael@0:                 Cr.NS_ERROR_INVALID_ARG,
michael@0:                 Components.stack.caller
michael@0:             );
michael@0:             throw exception;
michael@0:         }
michael@0: 
michael@0:         if (aOptions && "charset" in aOptions) {
michael@0:           let cis = Cc["@mozilla.org/intl/converter-input-stream;1"].
michael@0:                     createInstance(Ci.nsIConverterInputStream);
michael@0:           try {
michael@0:             // When replacement is set, the character that is unknown sequence 
michael@0:             // replaces with aOptions.replacement character.
michael@0:             if (!("replacement" in aOptions)) {
michael@0:               // aOptions.replacement isn't set.
michael@0:               // If input stream has unknown sequences for aOptions.charset,
michael@0:               // throw NS_ERROR_ILLEGAL_INPUT.
michael@0:               aOptions.replacement = 0;
michael@0:             }
michael@0: 
michael@0:             cis.init(aInputStream, aOptions.charset, aCount,
michael@0:                      aOptions.replacement);
michael@0:             let str = {};
michael@0:             cis.readString(-1, str);
michael@0:             cis.close();
michael@0:             return str.value;
michael@0:           }
michael@0:           catch (e) {
michael@0:             // Adjust the stack so it throws at the caller's location.
michael@0:             throw new Components.Exception(e.message, e.result,
michael@0:                                            Components.stack.caller, e.data);
michael@0:           }
michael@0:         }
michael@0: 
michael@0:         let sis = Cc["@mozilla.org/scriptableinputstream;1"].
michael@0:                   createInstance(Ci.nsIScriptableInputStream);
michael@0:         sis.init(aInputStream);
michael@0:         try {
michael@0:             return sis.readBytes(aCount);
michael@0:         }
michael@0:         catch (e) {
michael@0:             // Adjust the stack so it throws at the caller's location.
michael@0:             throw new Components.Exception(e.message, e.result,
michael@0:                                            Components.stack.caller, e.data);
michael@0:         }
michael@0:     },
michael@0: 
michael@0:     /**
michael@0:      * Returns a reference to nsIIOService.
michael@0:      *
michael@0:      * @return a reference to nsIIOService.
michael@0:      */
michael@0:     get ioService()
michael@0:     {
michael@0:         delete this.ioService;
michael@0:         return this.ioService = Cc["@mozilla.org/network/io-service;1"].
michael@0:                                 getService(Ci.nsIIOService);
michael@0:     },
michael@0: };
michael@0: 
michael@0: ////////////////////////////////////////////////////////////////////////////////
michael@0: //// Initialization
michael@0: 
michael@0: Components.utils.import("resource://gre/modules/XPCOMUtils.jsm");
michael@0: 
michael@0: // Define our lazy getters.
michael@0: XPCOMUtils.defineLazyServiceGetter(this, "ioUtil", "@mozilla.org/io-util;1",
michael@0:                                    "nsIIOUtil");