nsIScriptableInputStream

Method overview

Methods

available()

Return the number of bytes currently available in the stream.

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.

void close();

Parameters

None.

init()

Wrap the given nsIInputStream with this nsIScriptableInputStream.

void init(
  in nsIInputStream aInputStream
);

Parameters

aInputStream

The nsIInputStream to be wrapped.

read()

Read data from the stream.

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.

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.

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

• nsScriptableInputStream
• nsIInputStream