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:

• nsIOutputStream.idl