nsISupports
Last changed in Gecko 1.0 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.
Method overview
void close(); |
void flush(); |
boolean isNonBlocking(); |
unsigned long write(in string aBuf, in unsigned long aCount); |
unsigned long writeFrom(in nsIInputStream aFromStream, in unsigned long aCount); |
unsigned long writeSegments(in nsReadSegmentFun aReader, in voidPtr aClosure, in unsigned long aCount); Native code only! |
Methods
close()
Close the stream. Forces the output stream to flush()
any buffered data.
void close();
Parameters
None.
Exceptions thrown
-
NS_BASE_STREAM_WOULD_BLOCK
-
Indicates that closing the output stream would block the calling thread for an indeterminate amount of time. This exception may only be thrown if
isNonBlocking()
returns true.
flush()
This method may be called to instruct the output stream to write out the contents of any internal buffers to a low-level data sink, such as a file on disk. However, the flush method may simply do nothing depending on the implementation of the output stream.
void flush();
Parameters
None.
Exceptions thrown
-
NS_BASE_STREAM_WOULD_BLOCK
-
Indicates that flushing the output stream would block the calling thread for an indeterminate amount of time. This exception may only be thrown if
isNonBlocking()
returns true.
isNonBlocking()
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.boolean isNonBlocking();
Parameters
None.
Return value
true
if stream is non-blocking.
Exceptions thrown
-
NS_BASE_STREAM_WOULD_BLOCK
- A non-blocking stream may throw this exception when written to if space for the data is not immediately available.
write()
This method copies data from a buffer into the stream.
unsigned long write( in string aBuf, in unsigned long aCount );
Parameters
-
aBuf
- The buffer containing the data to be written.
-
aCount
- The size of the buffer, or the maximum number of bytes to copy from the buffer.
Return value
This method returns the number of bytes copied from the buffer (may be less than aCount).
Exceptions thrown
-
NS_BASE_STREAM_WOULD_BLOCK
- If writing to the output stream would block the calling thread (non-blocking mode only)
writeFrom()
This method copies data from an nsIInputStream
to this nsIOutputStream
.
A nsIOutputStream
is not required to implement this method. In some contexts, writeFrom
may be guaranteed to be implemented, but in general it is not. This method serves as an optimization.
Write()
method.unsigned long writeFrom( in nsIInputStream aFromStream, in unsigned long aCount );
Parameters
-
aFromStream
-
An
nsIInputStream
containing the data to be written. -
aCount
- The maximum number of bytes to write to the stream.
Return value
This method returns the number of bytes written to the stream (may be less than aCount).
Exceptions thrown
-
NS_BASE_STREAM_WOULD_BLOCK
-
Indicates that writing to the output stream would block the calling thread for an indeterminate amount of time. This exception may only be thrown if
isNonBlocking()
returns true. -
NS_ERROR_NOT_IMPLEMENTED
-
Indicates that the stream does not implement this method. Typically, output streams that do not have an internal buffer will not implement this method since such an implementation would require an intermediate buffer unless
aFromStream
supportednsIInputStream.readSegments()
, but that is not guaranteed.
writeSegments
Low-level write method that has access to the stream's underlying buffer. The reader function may be called multiple times for segmented buffers. This method is expected to keep calling the reader until either there is nothing left to write or the reader returns an error. This method should not call the reader with zero bytes to provide.
nsIOutputStream
is not required to implement this method. In some contexts, writeSegments
may be guaranteed to be implemented, but in general it is not. This method serves as an optimization.unsigned long writeSegments( in nsReadSegmentFun aReader, in voidPtr aClosure, in unsigned long aCount );
Parameters
-
aReader
-
A callback function that may be called multiple times. See
nsReadSegmentFun
for more details on this function. -
aClosure
- A parameter that is passed to aReader each time it is called.
-
aCount
- The maximum number of bytes to write to the stream.
Return value
This method returns the number of bytes written to the stream (may be less than aCount).
Exceptions thrown
-
NS_BASE_STREAM_WOULD_BLOCK
-
Indicates that writing to the output stream would block the calling thread for an indeterminate amount of time. This exception may only be thrown if
isNonBlocking()
returns true. -
NS_ERROR_NOT_IMPLEMENTED
- Indicates that the stream does not have an internal buffer that can be written to directly.
Example
writeSegments()
example
// Copy data from a string to a stream static NS_METHOD CopySegment(nsIInputStream* aStream, void* aClosure, char* aToSegment, PRUint32 aFromOffset, PRUint32 aCount, PRUint32* aReadCount) { // aFromSegment now contains aCount bytes of data. nsACString* pBuf = (nsACString*) aClosure; const char* data; PRUint32 len = NS_CStringGetData(&data); data += aFromOffset; len -= aFromOffset; if (len > aCount) len = aCount; memcpy(aToSegment, data, len); // Indicate that we have copied len bytes to the segment *aReadCount = len; return NS_OK; } // Write the contents of aSource into aStream, using WriteSegments // to avoid intermediate buffer copies. nsresult WriteStream(const nsACString& aSource, nsIInputStream* aStream) { PRUint32 num; return aStream->WriteSegments(CopySegment, (void*) &aSource, aSource.Length(), &num); }
Remarks
This interface was frozen for Gecko 1.0. See bug 124465 for details. From Gecko 2.0 interfaces are no longer frozen.