You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Skip to main content

TOC PREV NEXT INDEX

Embedding Gecko API

nsIInputStream

This interface manages reading data in from an input stream. It is partially scriptable.

Methods
close

Closes the stream.

Syntax: 

void nsIInputStream::close()

Parameters:

None.

nsresult:

NS_OK if successful.
available

Gets number of bytes currently available in the stream.

Syntax: 

unsigned long nsIInputStream::available()

Parameters:

None.

Returns:

The number of bytes.
read

Reads data from the stream. This method is not scriptable.

Syntax: 

unsigned long nsIInputStream::read(in charPtr aBuf, 
	in unsigned long aCount)

Parameters:

aBuf: The buffer into which the data is to be read.
aCount: The maximum number of bytes to be read.

Returns:

The number of bytes read. Returns 0 if end of file has been reached.
Throws NS_BASE_STREAM_WOULD_BLOCK if reading from the input stream would block the calling thread (non-blocking mode only).
Throws <other-error> on failure.
readSegments

Low-level read method that has access to the stream's underlying buffer. The writer function may be called multiple times for segmented buffers. This method is not scriptable.

Syntax: 

unsigned long nsIInputStream::readSegments(
	in nsWriteSegmentFun aWriter, in voidPtr aClosure, 
	in unsigned long aCount)

Parameters:

aWriter: The "consumer" of the data to be read. The type is described below.
aClosure: Opaque parameter passed to writer.
aCount: The maximum number of bytes to be read.
typedef NS_CALLBACK(nsWriteSegmentFun)(
		nsIInputStream *aInStream, 
		void *aClosure, 
		const char *aFromSegment, 
		PRUint32 aToOffset, 
		PRUint32 aCount, 
		PRUint32 *aWriteCount);

aInStream: The stream being read.
aClosure: Opaque parameter passed to readSegments.
aFromSegment: A pointer to memory owned by the input stream.
aToOffset: The amount already read (since readSegments was called).
aCount: The length of fromSegment.
aWriteCount: The number of bytes read.

Note: Implementers should return the following: NS_OK and (*aWriteCount > 0) if consumed some data; NS_BASE_STREAM_WOULD_BLOCK if not interested in consuming any data; <other-error> on failure. Errors are passed to the caller of ReadSegments, unless aToOffset is greater than zero.

Returning NS_OK and (*aWriteCount = 0) has undefined behavior.

Returns:

The number of bytes read. Returns 0 if end of file has been reached.
Throws NS_BASE_STREAM_WOULD_BLOCK if reading from the input stream would block the calling thread (non-blocking mode only).
Throws <other-error> on failure.

Note: This method may be unimplemented if a stream has no underlying buffer (e.g., socket input stream).

isNonBlocking

Returns TRUE if stream is non-blocking.

Syntax: 

boolean nsIInputStream::isNonBlocking()

Parameters:

None.

Returns:

TRUE if stream is non-blocking.
FALSE otherwise.
Written by:Ellen Evans | Comments, questions, complaints? Bug 143387
TOC PREV NEXT INDEX