Public Member Functions

nsIOutputStream Interface Reference

nsIOutputStream More...

import "nsIOutputStream.idl";

Inheritance diagram for nsIOutputStream:

List of all members.

Public Member Functions

void close ()
 Close the stream.
void flush ()
 Flush the stream.
unsigned long write (in string aBuf, in unsigned long aCount)
 Write data into the stream.
unsigned long writeFrom (in nsIInputStream aFromStream, in unsigned long aCount)
 Writes data into the stream from an input stream.
unsigned long writeSegments (in nsReadSegmentFun aReader, in voidPtr aClosure, in unsigned long aCount)
 Low-level write method that has access to the stream's underlying buffer.
boolean isNonBlocking ()

Detailed Description

nsIOutputStream

An interface describing a writable stream of data. An output stream may be "blocking" or "non-blocking" (see the IsNonBlocking method). A blocking output stream may suspend the calling thread in order to satisfy a call to Close, Flush, Write, WriteFrom, or WriteSegments. A non-blocking output stream, on the other hand, must not block the calling thread of execution.

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


Member Function Documentation

void nsIOutputStream::close (  ) 

Close the stream.

Forces the output stream to flush any buffered data.

Exceptions:
NS_BASE_STREAM_WOULD_BLOCK if unable to flush without blocking the calling thread (non-blocking mode only)
void nsIOutputStream::flush (  ) 

Flush the stream.

Exceptions:
NS_BASE_STREAM_WOULD_BLOCK if unable to flush without blocking the calling thread (non-blocking mode only)
boolean nsIOutputStream::isNonBlocking (  ) 
Returns:
true if stream is non-blocking

NOTE: writing to a blocking output stream will block the calling thread until all given data can be consumed by the stream.

NOTE: a non-blocking output stream may implement nsIAsyncOutputStream to provide consumers with a way to wait for the stream to accept more data once its write method is unable to accept any data without blocking.

unsigned long nsIOutputStream::write ( in string  aBuf,
in unsigned long  aCount 
)

Write data into the stream.

Parameters:
aBuf the buffer containing the data to be written
aCount the maximum number of bytes to be written
Returns:
number of bytes written (may be less than aCount)
Exceptions:
NS_BASE_STREAM_WOULD_BLOCK if writing to the output stream would block the calling thread (non-blocking mode only)
<other-error> on failure
unsigned long nsIOutputStream::writeFrom ( in nsIInputStream  aFromStream,
in unsigned long  aCount 
)

Writes data into the stream from an input stream.

Parameters:
aFromStream the stream containing the data to be written
aCount the maximum number of bytes to be written
Returns:
number of bytes written (may be less than aCount)
Exceptions:
NS_BASE_STREAM_WOULD_BLOCK if writing to the output stream would block the calling thread (non-blocking mode only)
<other-error> on failure

NOTE: This method is defined by this interface in order to allow the output stream to efficiently copy the data from the input stream into its internal buffer (if any). If this method was provided as an external facility, a separate char* buffer would need to be used in order to call the output stream's other Write method.

unsigned long nsIOutputStream::writeSegments ( in nsReadSegmentFun  aReader,
in voidPtr  aClosure,
in unsigned long  aCount 
)

Low-level write method that has access to the stream's underlying buffer.

The reader function may be called multiple times for segmented buffers. WriteSegments is expected to keep calling the reader until either there is nothing left to write or the reader returns an error. WriteSegments should not call the reader with zero bytes to provide.

Parameters:
aReader the "provider" of the data to be written
aClosure opaque parameter passed to reader
aCount the maximum number of bytes to be written
Returns:
number of bytes written (may be less than aCount)
Exceptions:
NS_BASE_STREAM_WOULD_BLOCK if writing to the output stream would block the calling thread (non-blocking mode only)
NS_ERROR_NOT_IMPLEMENTED if the stream has no underlying buffer
<other-error> on failure

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


The documentation for this interface was generated from the following file: