xpcom/io/nsIInputStream.idlScriptable
This interface represents a readable stream of data.
Inherits from: 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.

Note: Blocking input streams are often read on a background thread to avoid locking up the main application thread. For this reason, it is generally the case that a blocking input stream should be implemented using thread-safe AddRef and Release.

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.

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

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.

Note: The close method may be called more than once, but subsequent calls are ignored.

void close();
Parameters

None.

isNonBlocking()

boolean isNonBlocking();
Parameters

None.

Return value

true if stream is non-blocking.

Native code only!

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.

Native code only!

readSegments

This method provides direct access to the stream's internal buffer.

Note: A 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