Struct xpcom::interfaces::nsIAsyncInputStream

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

interface nsIAsyncInputStream : nsIInputStream

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

Methods

impl nsIAsyncInputStream

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

Cast this nsIAsyncInputStream to one of its base interfaces.

impl nsIAsyncInputStream

pub const WAIT_CLOSURE_ONLY: i64

WAIT_CLOSURE_ONLY: i64 = 1

/**
     * If passed to asyncWait, this flag overrides the default behavior,
     * causing the OnInputStreamReady 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, aStatus: 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
     * has an effect 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 input end of a pipe is closed, then
     * writes to the output end of the pipe will fail.  The error code returned
     * when an attempt is made to write to a "broken" pipe corresponds to the
     * status code passed in when the input end of the pipe was 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 aStatus);

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

/**
     * Asynchronously wait for the stream to be readable or closed.  The
     * notification is one-shot, meaning that each asyncWait call will result
     * in exactly one notification callback.  After the OnInputStreamReady event
     * is dispatched, the stream releases its reference to the
     * nsIInputStreamCallback object.  It is safe to call asyncWait again from the
     * notification handler.
     *
     * This method may be called at any time (even if read has not been called).
     * In other words, this method may be called when the stream already has
     * data to read.  It may also be called when the stream is closed.  If the
     * stream is already readable or closed when AsyncWait is called, then the
     * OnInputStreamReady event will be dispatched immediately.  Otherwise, the
     * event will be dispatched when the stream becomes readable 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 read.  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 nsIInputStreamCallback aCallback, in unsigned long aFlags, in unsigned long aRequestedCount, in nsIEventTarget aEventTarget);

Methods from Deref<Target = nsIInputStream>

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

Cast this nsIInputStream to one of its base interfaces.

pub unsafe fn Close(&self) -> nsresult

/**
 * nsIInputStream
 *
 * An interface describing a readable stream of data.  An input stream may be
 * "blocking" or "non-blocking" (see the IsNonBlocking method).  A blocking
 * input stream may suspend the calling thread in order to satisfy a call to
 * Close, Available, Read, or ReadSegments.  A non-blocking input stream, on
 * the other hand, must not block the calling thread of execution.
 *
 * NOTE: blocking input streams are often read on a background thread to avoid
 * locking up the main application thread.  For this reason, it is generally
 * the case that a blocking input stream should be implemented using thread-
 * safe AddRef and Release.
 */
/**
     * Close the stream.  This method causes subsequent calls to Read and
     * ReadSegments to return 0 bytes read to indicate end-of-file.  Any
     * subsequent calls to Available should throw NS_BASE_STREAM_CLOSED.
     */

void close ();

pub unsafe fn Available(&self, _retval: *mut uint64_t) -> nsresult

/**
     * Determine number of bytes available in the stream.  A non-blocking
     * stream that does not yet have any data to read should return 0 bytes
     * from this method (i.e., it must not throw the NS_BASE_STREAM_WOULD_BLOCK
     * exception).
     *
     * In addition to the number of bytes available in the stream, this method
     * also informs the caller of the current status of the stream.  A stream
     * that is closed will throw an exception when this method is called.  That
     * enables the caller to know the condition of the stream before attempting
     * to read from it.  If a stream is at end-of-file, but not closed, then
     * this method returns 0 bytes available.  (Note: some nsIInputStream
     * implementations automatically close when eof is reached; some do not).
     *
     * @return number of bytes currently available in the stream.
     *
     * @throws NS_BASE_STREAM_CLOSED if the stream is closed normally.
     * @throws <other-error> if the stream is closed due to some error
     *   condition
     */

unsigned long long available ();

pub unsafe fn Read(
    &self,
    aBuf: *mut u8,
    aCount: uint32_t,
    _retval: *mut uint32_t
) -> nsresult

/**
     * Read data from the stream.
     *
     * @param aBuf the buffer into which the data is to be read
     * @param aCount the maximum number of bytes to be read
     *
     * @return number of bytes read (may be less than aCount).
     * @return 0 if reached end-of-file
     *
     * @throws NS_BASE_STREAM_WOULD_BLOCK if reading from the input stream would
     *   block the calling thread (non-blocking mode only)
     * @throws <other-error> on failure
     *
     * NOTE: this method should not throw NS_BASE_STREAM_CLOSED.
     */

[noscript] unsigned long read (in charPtr aBuf, in unsigned long aCount);

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

/**
     * @return true if stream is non-blocking
     *
     * NOTE: reading from a blocking input stream will block the calling thread
     * until at least one byte of data can be extracted from the stream.
     *
     * NOTE: a non-blocking input stream may implement nsIAsyncInputStream to
     * provide consumers with a way to wait for the stream to have more data
     * once its read method is unable to return any data without blocking.
     */

boolean isNonBlocking ();

Trait Implementations

impl XpCom for nsIAsyncInputStream

const IID: nsIID

IID: nsIID = nsID(2784122283, 18433, 16737, [136, 22, 39, 122, 201, 47, 106, 209])

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 nsIAsyncInputStream

unsafe fn addref(&self)

Increment the reference count.

unsafe fn release(&self)

Decrement the reference count, potentially freeing backing memory.

impl Deref for nsIAsyncInputStream

type Target = nsIInputStream

The resulting type after dereferencing.

fn deref(&self) -> &nsIInputStream

Dereferences the value.