xpcom/io/nsIScriptableInputStream.idlScriptable
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()

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