mozilla
Your Search Results

    nsIScriptableInputStream

    This interface provides scriptable access to a nsIInputStream instance.
    Inherits from: nsISupports Last changed in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

    Method overview

    unsigned long available();
    void close();
    void init(in nsIInputStream aInputStream);
    string read(in unsigned long aCount);
    ACString readBytes(in unsigned long aCount);

    Methods

    available()

    Return the number of bytes currently available in the stream.

    Note: This method should not be used to determine the total size of a stream, even if the stream corresponds to a local file. Moreover, since a stream may make available more than 2^32 bytes of data, this method is incapable of expressing the entire size of the underlying data source.

    unsigned long available();
    
    Parameters

    None.

    Return value

    The number of bytes.

    Exceptions thrown
    NS_BASE_STREAM_CLOSED
    If called after the stream has been closed.

    close()

    Closes the stream.

    Note: The close method may be called more than once, but subsequent calls are ignored.

    void close();
    
    Parameters

    None.

    init()

    Wrap the given nsIInputStream with this nsIScriptableInputStream.

    Note: The init method may be called more than once, allowing a nsIScriptableInputStream instance to be reused.

    void init(
      in nsIInputStream aInputStream
    );
    
    Parameters
    aInputStream
    The nsIInputStream to be wrapped.

    read()

    Read data from the stream.

    Warning: If the data contains a null byte, then this method will return a truncated string.

    Note: It is also important to consider how a language bindings may interpret the string data type. In particular, some bindings may convert the byte values into Unicode code points, by assuming the byte values are encoded as ISO-Latin-1. This is the case for the JavaScript bindings.

    string read(
      in unsigned long aCount
    );
    
    Parameters
    aCount
    The maximum number of bytes to read from the stream.
    Return value

    The data read as a string, which will be an empty string if the stream is at EOF.

    Exceptions thrown
    NS_ERROR_NOT_INITIALIZED
    If init() was not called.
    NS_BASE_STREAM_CLOSED
    If called after the stream has been closed.
    NS_BASE_STREAM_WOULD_BLOCK
    Indicates that reading from the input stream would block the calling thread for an indeterminate amount of time. This exception may only be thrown if nsIInputStream.isNonBlocking() returns true.

    readBytes()

    Requires Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

    Read data from the stream, including null bytes.

    ACString readBytes(
      in unsigned long aCount
    );
    
    Parameters
    aCount
    The maximum number of bytes to read.
    Return value

    The data from the stream, which will be an empty string if EOF has been reached.

    Exceptions thrown
    NS_ERROR_FAILURE
    If there are not enough bytes available to read aCount amount of data.
    NS_BASE_STREAM_WOULD_BLOCK
    If reading from the input stream would block the calling thread (non-blocking mode only).

    Remarks

    This interface provides JavaScript with a way to read ASCII text from a nsIInputStream. However, it does not address the problem of reading arbitrary binary data from a stream. For binary input see nsIBinaryInputStream.

    Note: Starting in Gecko 2.0, you can use the NetUtils.jsm JavaScript code module and its readInputStreamToString() method to read arbitrary binary data into a JavaScript string.

    The nsScriptableInputStream component implements this interface.

    This interface was frozen for Gecko 1.2. From Gecko 2.0 interfaces are no longer frozen.

    Examples

    List contents of XPI and read file contents

    This example here uses the read function. It takes a input stream from the zip reader and outputs the text in it. Full example using the zip interfaces is seen here: List contents of XPI and read file contents. Remember: The nsIScriptableInputStream has a contract where `init` should only be called once, and should always be closed. Excerpt of the stream for this stream article is here, this is only an excerpt so cannot copy paste this code into scratchpad.

    var {classes: Cc, interfaces: Ci, results: Cr, Constructor: CC, utils: Cu } = Components;
    var ScriptableInputStream = CC("@mozilla.org/scriptableinputstream;1", "nsIScriptableInputStream", "init");
    
    
        let entry = this.getEntry(name);
        let stream = new ScriptableInputStream(this.getInputStream(name));
        try {
          // Use readBytes to get binary data, read to read a (null-terminated) string
          let contents = stream.readBytes(entry.realSize);
        }
        finally {
          stream.close();
        }

    Example usage in onDataAvailable

    Remember: The nsIScriptableInputStream has a contract where `init` should only be called once, and should always be closed.

    var ScriptableInputStream = CC("@mozilla.org/scriptableinputstream;1", "nsIScriptableInputStream", "init");
    
    var blah = {
        data: '',
        onStartRequest: function (aRequest, aContext) {
            this.data = '';
        },
        onDataAvailable: function(request, context, inputStream, offset, count) {
            var scriptStream = new ScriptableInputStream(inputStream);
            this.data += scriptStream.read(count);
            scriptStream.close();
        }
    };

    See also

    Document Tags and Contributors

    Last updated by: dcolascione,