nsIInputStream

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

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.

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.

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.

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

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.