mozilla
Your Search Results

    nsIInputStream

    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;
      PRUint32 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,
                                   PRUint32 aToOffset,
                                   PRUint32 aCount,
                                   PRUint32* 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)
    {
      PRUint32 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

    Document Tags and Contributors

    Contributors to this page: trevorh
    Last updated by: trevorh,