1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/xpcom/io/nsIOutputStream.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,143 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +interface nsIOutputStream;
1.12 +interface nsIInputStream;
1.13 +
1.14 +%{C++
1.15 +/**
1.16 + * The signature for the reader function passed to WriteSegments. This
1.17 + * is the "provider" of data that gets written into the stream's buffer.
1.18 + *
1.19 + * @param aOutStream stream being written to
1.20 + * @param aClosure opaque parameter passed to WriteSegments
1.21 + * @param aToSegment pointer to memory owned by the output stream
1.22 + * @param aFromOffset amount already written (since WriteSegments was called)
1.23 + * @param aCount length of toSegment
1.24 + * @param aReadCount number of bytes written
1.25 + *
1.26 + * Implementers should return the following:
1.27 + *
1.28 + * @throws <any-error> if not interested in providing any data
1.29 + *
1.30 + * Errors are never passed to the caller of WriteSegments.
1.31 + */
1.32 +typedef NS_CALLBACK(nsReadSegmentFun)(nsIOutputStream *aOutStream,
1.33 + void *aClosure,
1.34 + char *aToSegment,
1.35 + uint32_t aFromOffset,
1.36 + uint32_t aCount,
1.37 + uint32_t *aReadCount);
1.38 +%}
1.39 +
1.40 +native nsReadSegmentFun(nsReadSegmentFun);
1.41 +
1.42 +/**
1.43 + * nsIOutputStream
1.44 + *
1.45 + * An interface describing a writable stream of data. An output stream may be
1.46 + * "blocking" or "non-blocking" (see the IsNonBlocking method). A blocking
1.47 + * output stream may suspend the calling thread in order to satisfy a call to
1.48 + * Close, Flush, Write, WriteFrom, or WriteSegments. A non-blocking output
1.49 + * stream, on the other hand, must not block the calling thread of execution.
1.50 + *
1.51 + * NOTE: blocking output streams are often written to on a background thread to
1.52 + * avoid locking up the main application thread. For this reason, it is
1.53 + * generally the case that a blocking output stream should be implemented using
1.54 + * thread- safe AddRef and Release.
1.55 + */
1.56 +[scriptable, uuid(0d0acd2a-61b4-11d4-9877-00c04fa0cf4a)]
1.57 +interface nsIOutputStream : nsISupports
1.58 +{
1.59 + /**
1.60 + * Close the stream. Forces the output stream to flush any buffered data.
1.61 + *
1.62 + * @throws NS_BASE_STREAM_WOULD_BLOCK if unable to flush without blocking
1.63 + * the calling thread (non-blocking mode only)
1.64 + */
1.65 + void close();
1.66 +
1.67 + /**
1.68 + * Flush the stream.
1.69 + *
1.70 + * @throws NS_BASE_STREAM_WOULD_BLOCK if unable to flush without blocking
1.71 + * the calling thread (non-blocking mode only)
1.72 + */
1.73 + void flush();
1.74 +
1.75 + /**
1.76 + * Write data into the stream.
1.77 + *
1.78 + * @param aBuf the buffer containing the data to be written
1.79 + * @param aCount the maximum number of bytes to be written
1.80 + *
1.81 + * @return number of bytes written (may be less than aCount)
1.82 + *
1.83 + * @throws NS_BASE_STREAM_WOULD_BLOCK if writing to the output stream would
1.84 + * block the calling thread (non-blocking mode only)
1.85 + * @throws <other-error> on failure
1.86 + */
1.87 + unsigned long write(in string aBuf, in unsigned long aCount);
1.88 +
1.89 + /**
1.90 + * Writes data into the stream from an input stream.
1.91 + *
1.92 + * @param aFromStream the stream containing the data to be written
1.93 + * @param aCount the maximum number of bytes to be written
1.94 + *
1.95 + * @return number of bytes written (may be less than aCount)
1.96 + *
1.97 + * @throws NS_BASE_STREAM_WOULD_BLOCK if writing to the output stream would
1.98 + * block the calling thread (non-blocking mode only)
1.99 + * @throws <other-error> on failure
1.100 + *
1.101 + * NOTE: This method is defined by this interface in order to allow the
1.102 + * output stream to efficiently copy the data from the input stream into
1.103 + * its internal buffer (if any). If this method was provided as an external
1.104 + * facility, a separate char* buffer would need to be used in order to call
1.105 + * the output stream's other Write method.
1.106 + */
1.107 + unsigned long writeFrom(in nsIInputStream aFromStream,
1.108 + in unsigned long aCount);
1.109 +
1.110 + /**
1.111 + * Low-level write method that has access to the stream's underlying buffer.
1.112 + * The reader function may be called multiple times for segmented buffers.
1.113 + * WriteSegments is expected to keep calling the reader until either there
1.114 + * is nothing left to write or the reader returns an error. WriteSegments
1.115 + * should not call the reader with zero bytes to provide.
1.116 + *
1.117 + * @param aReader the "provider" of the data to be written
1.118 + * @param aClosure opaque parameter passed to reader
1.119 + * @param aCount the maximum number of bytes to be written
1.120 + *
1.121 + * @return number of bytes written (may be less than aCount)
1.122 + *
1.123 + * @throws NS_BASE_STREAM_WOULD_BLOCK if writing to the output stream would
1.124 + * block the calling thread (non-blocking mode only)
1.125 + * @throws NS_ERROR_NOT_IMPLEMENTED if the stream has no underlying buffer
1.126 + * @throws <other-error> on failure
1.127 + *
1.128 + * NOTE: this function may be unimplemented if a stream has no underlying
1.129 + * buffer (e.g., socket output stream).
1.130 + */
1.131 + [noscript] unsigned long writeSegments(in nsReadSegmentFun aReader,
1.132 + in voidPtr aClosure,
1.133 + in unsigned long aCount);
1.134 +
1.135 + /**
1.136 + * @return true if stream is non-blocking
1.137 + *
1.138 + * NOTE: writing to a blocking output stream will block the calling thread
1.139 + * until all given data can be consumed by the stream.
1.140 + *
1.141 + * NOTE: a non-blocking output stream may implement nsIAsyncOutputStream to
1.142 + * provide consumers with a way to wait for the stream to accept more data
1.143 + * once its write method is unable to accept any data without blocking.
1.144 + */
1.145 + boolean isNonBlocking();
1.146 +};
