/**
 * Goals:
 *
 *  (1) Model streams after NSPR I/O, thus making implementation easy and transparent
 *  (2) Allow both - blocking and non-blocking operations within the same API framework
 *      and in doing so streamlining the way application is developed
 *  (3) All stream implenetations become uniformed in both - blocking and non0blocking
 *      modes, thus taking partially the functionality of nsIOChannel's and allow simple
 *      transparent chaining of streams without encouraging excessive buffering
 *
 *  This model will not support NT-style overlapped I/O; there's no good expression for it
 *  within NSPR either - do we need it?
 *
 *  Changes:
 *      gagan:  streams will not inherit from nsI*Stream to not confuse them with existing
 *              streams as behavior is a bit different
 *      ruslan: streams will not have a common base class and Close () operation - this will
 *              have to be done in the destructor
 *      ruslan: output stream will not have Flush () operation - this will need to  be moved
 *              into some new BufferedWriter interface
 */

#include "nsISupports.idl"
#include "nsISimpleFailure.idl"
#include "nsICompletionEventListener.idl"

[scriptable, uuid(295c8dfa-7031-4615-a6c9-ddb692901035)]
interface nsIOutputStream2 : nsISupports
{
    /** Write data into the stream.
     *  @param aBuf the buffer from which the data is read
     *  @param aCount the maximum number of bytes to write
     *  @return aWriteCount out parameter to hold the number of
     *         bytes written. if an error occurs, the writecount
     *         is undefined
     */
    unsigned long Write(in string buf, in unsigned long count);

    /**
     * Optional attribute which defines expected data length of the output
     * stream. It's purpose in life is to aid i/o layers whith the length
     * of the stream externally prescribed
     */
    attribute long      Length;

    /**
     * a number of bytes written into the stream
     */
    readonly  attribute  unsigned long	Count;

    /**
     * This attribute determines whether Read would block or not. In case of
     * a non-blocking stream - completion listener will be called only when
     * Write returns WOULD_BLOCK. Stream implementations are expected to be
     * able to switch between blocking and non-blocking modes on the fly
     */
    attribute boolean   Blocking;

    /**
     * Optional completion listener: the listener will only be used when Write
     * or Flush returns WOULD_BLOCK.
     */
    attribute nsICompletionEventListener    Listener;

    readonly attribute nsISimpleFailure     StreamError;
};
