nsISupports
Last changed in Gecko 17.0 (Firefox 17.0 / Thunderbird 17.0 / SeaMonkey 2.14)An input stream may be "blocking" or "non-blocking" (see the isNonBlocking()
method). A blocking input stream may suspend the calling thread in order to satisfy a call to close()
, available()
, read()
, or readSegments()
. A non-blocking input stream, on the other hand, must not block the calling thread of execution.
Method overview
unsigned long available(); Deprecated since Gecko 17.0 |
unsigned long long available(); |
void close(); |
boolean isNonBlocking(); |
unsigned long read(in charPtr aBuf, in unsigned long aCount); Native code only! |
unsigned long readSegments(in nsWriteSegmentFun aWriter, in voidPtr aClosure, in unsigned long aCount); Native code only! |
Methods
available()
Determine number of bytes available in the stream.
In addition to the number of bytes available in the stream, this method also informs the caller of the current status of the stream. A stream that is closed will throw an exception when this method is called. That enables the caller to know the condition of the stream before attempting to read from it. If a stream is at end-of-file, but not closed, then this method returns 0 bytes available.
Note: Some nsIInputStream
implementations automatically close()
when end-of-file is reached; others do not.
unsigned long available();
Parameters
None.
Return value
Number of bytes currently available in the stream, or PR_UINT32_MAX
if the size of the stream exceeds PR_UINT32_MAX
.
Exceptions thrown
<other-error>
- If the stream is closed due to some error condition.
NS_BASE_STREAM_CLOSED
- If the stream is closed normally.
close()
Close the stream. This method causes subsequent calls to read()
and readSegments()
to return 0 bytes read to indicate end-of-file.
void close();
Parameters
None.
isNonBlocking()
boolean isNonBlocking();
Parameters
None.
Return value
true
if stream is non-blocking.
read
This method copies data from the stream into a buffer.
unsigned long read( in charPtr aBuf, in unsigned long aCount );
Parameters
aBuf
- The buffer into which the data from the stream is copied.
aCount
- The size of the buffer, or the maximum number of bytes to copy from the stream.
Return value
This method returns the number of bytes copied from the stream (may be less than aCount). It returns 0 to indicate end-of-file.
Exceptions thrown
<other-error>
- On failure.
NS_BASE_STREAM_WOULD_BLOCK
- Indicates that reading from the input stream would block the calling thread for indeterminate amount of time. This exception may only be thrown if
isNonBlocking()
returns true.
readSegments
This method provides direct access to the stream's internal buffer.
nsIInputStream
is not required to implement this method. In some contexts, readSegments
may be guaranteed to be implemented, but in general it is not. This method serves as an optimization.unsigned long readSegments( in nsWriteSegmentFun aWriter, in voidPtr aClosure, in unsigned long aCount );
Parameters
aWriter
- The "consumer" of the data to be read. A callback function that may be called once for each buffer segment contained in the stream. See
nsWriteSegmentFun
for more details on this function. aClosure
- A parameter that is passed to aWriter each time it is called.
aCount
- The maximum number of bytes to read from the stream.
Return value
The number of bytes read from the stream (may be less than aCount). It returns 0 to indicate end-of-file.
Exceptions thrown
<other-error>
- On failure.
NS_ERROR_NOT_IMPLEMENTED
- Indicates that the stream does not have an internal buffer that can be accessed directly.
NS_BASE_STREAM_WOULD_BLOCK
- Indicates that reading from the input stream would block the calling thread for indeterminate amount of time. This exception may only be thrown if
isNonBlocking()
returns true.
Example
Consume all data from an input stream using read()
.
nsresult ConsumeStream(nsIInputStream* aStream) { nsresult rv; uint32_t numRead; char buf[512]; while (1) { rv = aStream->Read(buf, sizeof(buf), &numRead); if (NS_FAILED(rv)) { printf("### error reading stream: %x\n", rv); break; } if (numRead == 0) break; // buf now contains numRead bytes of data } return rv; }
Consume all data from an input stream using readSegments()
.
static NS_METHOD AppendSegment(nsIInputStream* aStream, void* aClosure, const char* aFromSegment, uint32_t aToOffset, uint32_t aCount, uint32_t* aWriteCount) { // aFromSegment now contains aCount bytes of data. nsACString* pBuf = (nsACString*) aClosure; pBuf->Append(aFromSegment, aCount); // Indicate that we have consumed all of aFromSegment *aWriteCount = aCount; return NS_OK; } // Copy the contents of aStream into aResultBuf as one contiguous // buffer. Use ReadSegments to avoid an intermediate buffer copy. nsresult CopyStream(nsIInputStream* aStream, nsACString& aResultBuf) { uint32_t numRead; return aStream->ReadSegments(AppendSegment, (void*) &aResultBuf, PR_UINT32_MAX, &numRead); }
Remarks
This interface was frozen for Gecko 1.0. See bug 124465 for details. From Gecko 2.0 interfaces are no longer frozen.
See also
nsIWriteSegmentFun
nsIScriptableInputStream
- If you need to read a stream from JavaScript.