nsIInputStream

IID:fa9c7f6c-61b3-11d4-9877-00c04fa0cf4a
Inherits From:nsISupports

This interface is implemented by the following components:


Methods

PRUint32 available ( ) void close ( ) PRBool isNonBlocking ( ) [noscript] PRUint32 read ( charPtr* buf , PRUint32 count ) [noscript] PRUint32 readSegments ( nsWriteSegmentFun writer , voidPtr* closure , PRUint32 count )

PRUint32 available ( )

Returns:
number of bytes currently available in the stream

void close ( )

Close the stream.


PRBool isNonBlocking ( )

Returns:
true if stream is non-blocking

PRUint32 read ( charPtr* buf , PRUint32 count )

Read data from the stream.

Arguments:
buf: the buffer into which the data is to be read
count: the maximum number of bytes to be read
Returns:
0 if reached end of file

PRUint32 readSegments ( nsWriteSegmentFun writer , voidPtr* closure , PRUint32 count )

Low-level read method that has access to the stream's underlying buffer. The writer function may be called multiple times for segmented buffers. ReadSegments is expected to keep calling the writer until either there is nothing left to read or the writer returns an error. ReadSegments should not call the writer with zero bytes to consume.

NOTE: this function may be unimplemented if a stream has no underlying buffer (e.g., socket input stream).

Arguments:
writer: the "consumer" of the data to be read
closure: opaque parameter passed to writer
count: the maximum number of bytes to be read
Returns:
0 if reached end of file (or if aWriter refused to consume data)

References

This interface is the type of the following properties:

nsIDOMLSInput.byteStream, nsIDocShellLoadInfo.headersStream, nsIDocShellLoadInfo.postDataStream, nsIFastLoadFileIO.inputStream, nsIFileSpec.inputStream, nsIInputStreamChannel.contentStream, nsIInputStreamTee.source, nsIMsgFolder.offlineStoreInputStream, nsIMsgSearchScopeTerm.inputStream, nsISHEntry.postData, nsISyncStreamListener.inputStream, nsIUploadChannel.uploadStream

This interface is passed as an argument to the following methods:

imgIDecoder.writeFrom, nsIAsyncStreamCopier.init, nsIBinaryInputStream.setInputStream, nsIBufferedInputStream.init, nsIConverterInputStream.init, nsICopyMessageListener.copyData, nsICryptoHash.updateFromStream, nsIDOMParser.parseFromStream, nsIDocShell.internalLoad, nsIDocShell.loadStream, nsIFastLoadService.newInputStream, nsIInputStreamPump.init, nsIMIMEInputStream.setData, nsIMimeEmitter.SetPipe, nsIMsgFolder.copyDataToOutputStreamForAppend, nsIMultiplexInputStream.appendStream, nsIMultiplexInputStream.insertStream, nsIOutputStream.writeFrom, nsIPersistentProperties.load, nsIPluginStreamListener.onDataAvailable, nsISHEntry.create, nsIScriptableInputStream.init, nsIStreamConverter.convert, nsIStreamConverterService.convert, nsIStreamListener.onDataAvailable, nsIStreamTransportService.createInputTransport, nsIUploadChannel.setUploadStream, nsIWebBrowserPersist.saveURI, nsIWebNavigation.loadURI, nsIXPTLoaderSink.foundEntry

This interface is returned from the following methods:

nsICacheEntryDescriptor.openInputStream, nsIChannel.open, nsIMsgFolder.getOfflineFileStream, nsIMultiplexInputStream.getStream, nsIScriptableUnicodeConverter.convertToInputStream, nsIStorageStream.newInputStream, nsIStreamConverter.convert, nsIStreamConverterService.convert, nsITransport.openInputStream, nsIXPTLoader.loadEntry, nsIZipReader.getInputStream

Reference documentation is generated from Mozilla's source.

Add a note User Contributed Notes
December 30, 2004, 4:59 pm mook dot moz at gmail dot com
From nsIInputStream.idl

(readSegments is kinda useless unless you can give it the right callback...)

nsWriteSegmentFun:

@param aInStream stream being read
@param aClosure opaque parameter passed to ReadSegments
@param aFromSegment pointer to memory owned by the input stream
@param aToOffset amount already read (since ReadSegments was called)
@param aCount length of fromSegment
@param aWriteCount number of bytes read

@return NS_OK and (*aWriteCount > 0) if consumed some data
@return <any-error> if not interested in consuming any data

Errors are never passed to the caller of ReadSegments.
NOTE: returning NS_OK and (*aWriteCount = 0) has undefined behavior.


nsWriteSegmentFun(nsIInputStream *aInStream,
void *aClosure,
const char *aFromSegment,
PRUint32 aToOffset,
PRUint32 aCount,
PRUint32 *aWriteCount);

Note: aFromSegment already has aToOffset applied to it; do not add aToOffset again. (I.e., aFromSegment does not necessarily point to the start of the stream.)

Copyright © 1999 - 2005 XULPlanet.com