Struct xpcom::interfaces::nsIAsyncOutputStream

#[repr(C)]
pub struct nsIAsyncOutputStream { /* fields omitted */ }

interface nsIAsyncOutputStream : nsIOutputStream

/**
 * If an output stream is non-blocking, it may return NS_BASE_STREAM_WOULD_BLOCK
 * when written to.  The caller must then wait for the stream to become
 * writable.  If the stream implements nsIAsyncOutputStream, then the caller can
 * use this interface to request an asynchronous notification when the stream
 * becomes writable or closed (via the AsyncWait method).
 *
 * While this interface is almost exclusively used with non-blocking streams, it
 * is not necessary that nsIOutputStream::isNonBlocking return true.  Nor is it
 * necessary that a non-blocking nsIOutputStream implementation also implement
 * nsIAsyncOutputStream.
 */

Methods

impl nsIAsyncOutputStream

pub fn coerce<T: nsIAsyncOutputStreamCoerce>(&self) -> &T

Cast this nsIAsyncOutputStream to one of its base interfaces.

impl nsIAsyncOutputStream

pub const WAIT_CLOSURE_ONLY: i64

WAIT_CLOSURE_ONLY: i64 = 1

/**
     * If passed to asyncWait, this flag overrides the default behavior,
     * causing the OnOutputStreamReady notification to be suppressed until the
     * stream becomes closed (either as a result of closeWithStatus/close being
     * called on the stream or possibly due to some error in the underlying
     * stream).
     */

pub unsafe fn CloseWithStatus(&self, reason: nsresult) -> nsresult

/**
     * This method closes the stream and sets its internal status.  If the
     * stream is already closed, then this method is ignored.  Once the stream
     * is closed, the stream's status cannot be changed.  Any successful status
     * code passed to this method is treated as NS_BASE_STREAM_CLOSED, which
     * is equivalent to nsIInputStream::close.
     *
     * NOTE: this method exists in part to support pipes, which have both an
     * input end and an output end.  If the output end of a pipe is closed, then
     * reads from the input end of the pipe will fail.  The error code returned
     * when an attempt is made to read from a "closed" pipe corresponds to the
     * status code passed in when the output end of the pipe is closed, which
     * greatly simplifies working with pipes in some cases.
     *
     * @param aStatus
     *        The error that will be reported if this stream is accessed after
     *        it has been closed.
     */

void closeWithStatus (in nsresult reason);

pub unsafe fn AsyncWait(
    &self,
    aCallback: *const nsIOutputStreamCallback,
    aFlags: uint32_t,
    aRequestedCount: uint32_t,
    aEventTarget: *const nsIEventTarget
) -> nsresult

/**
     * Asynchronously wait for the stream to be writable or closed.  The
     * notification is one-shot, meaning that each asyncWait call will result
     * in exactly one notification callback.  After the OnOutputStreamReady event
     * is dispatched, the stream releases its reference to the
     * nsIOutputStreamCallback object.  It is safe to call asyncWait again from the
     * notification handler.
     *
     * This method may be called at any time (even if write has not been called).
     * In other words, this method may be called when the stream already has
     * room for more data.  It may also be called when the stream is closed.  If
     * the stream is already writable or closed when AsyncWait is called, then the
     * OnOutputStreamReady event will be dispatched immediately.  Otherwise, the
     * event will be dispatched when the stream becomes writable or closed.
     *
     * @param aCallback
     *        This object is notified when the stream becomes ready.  This
     *        parameter may be null to clear an existing callback.
     * @param aFlags
     *        This parameter specifies optional flags passed in to configure
     *        the behavior of this method.  Pass zero to specify no flags.
     * @param aRequestedCount
     *        Wait until at least this many bytes can be written.  This is only
     *        a suggestion to the underlying stream; it may be ignored.  The
     *        caller may pass zero to indicate no preference.
     * @param aEventTarget
     *        Specify NULL to receive notification on ANY thread (possibly even
     *        recursively on the calling thread -- i.e., synchronously), or
     *        specify that the notification be delivered to a specific event
     *        target.
     */

void asyncWait (in nsIOutputStreamCallback aCallback, in unsigned long aFlags, in unsigned long aRequestedCount, in nsIEventTarget aEventTarget);

Methods from Deref<Target = nsIOutputStream>

pub fn coerce<T: nsIOutputStreamCoerce>(&self) -> &T

Cast this nsIOutputStream to one of its base interfaces.

pub unsafe fn Close(&self) -> nsresult

/**
 * 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.
 */
/**
     * Close the stream. Forces the output stream to flush any buffered data.
     *
     * @throws NS_BASE_STREAM_WOULD_BLOCK if unable to flush without blocking
     *   the calling thread (non-blocking mode only)
     */

void close ();

pub unsafe fn Flush(&self) -> nsresult

/**
     * Flush the stream.
     *
     * @throws NS_BASE_STREAM_WOULD_BLOCK if unable to flush without blocking
     *   the calling thread (non-blocking mode only)
     */

void flush ();

pub unsafe fn Write(
    &self,
    aBuf: *const c_char,
    aCount: uint32_t,
    _retval: *mut uint32_t
) -> nsresult

/**
     * Write data into the stream.
     *
     * @param aBuf the buffer containing the data to be written
     * @param aCount the maximum number of bytes to be written
     *
     * @return number of bytes written (may be less than aCount)
     *
     * @throws NS_BASE_STREAM_WOULD_BLOCK if writing to the output stream would
     *   block the calling thread (non-blocking mode only)
     * @throws <other-error> on failure
     */

unsigned long write (in string aBuf, in unsigned long aCount);

pub unsafe fn WriteFrom(
    &self,
    aFromStream: *const nsIInputStream,
    aCount: uint32_t,
    _retval: *mut uint32_t
) -> nsresult

/**
     * Writes data into the stream from an input stream.
     *
     * @param aFromStream the stream containing the data to be written
     * @param aCount the maximum number of bytes to be written
     *
     * @return number of bytes written (may be less than aCount)
     *
     * @throws NS_BASE_STREAM_WOULD_BLOCK if writing to the output stream would
     *    block the calling thread (non-blocking mode only). This failure
     *    means no bytes were transferred.
     * @throws <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 writeFrom (in nsIInputStream aFromStream, in unsigned long aCount);

pub unsafe fn IsNonBlocking(&self, _retval: *mut bool) -> nsresult

/**
     * @return 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.
     */

boolean isNonBlocking ();

Trait Implementations

impl XpCom for nsIAsyncOutputStream

const IID: nsIID

IID: nsIID = nsID(3199611603, 55162, 20112, [145, 52, 249, 236, 230, 158, 130, 0])

fn query_interface<T: XpCom>(&self) -> Option<RefPtr<T>>

Perform a QueryInterface call on this object, attempting to dynamically cast it to the requested interface type. Returns Some(RefPtr) if the cast succeeded, and None otherwise.

impl RefCounted for nsIAsyncOutputStream

unsafe fn addref(&self)

Increment the reference count.

unsafe fn release(&self)

Decrement the reference count, potentially freeing backing memory.

impl Deref for nsIAsyncOutputStream

type Target = nsIOutputStream

The resulting type after dereferencing.

fn deref(&self) -> &nsIOutputStream

Dereferences the value.