gecko-dev/netwerk/base/public/nsITransport.idl

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * The contents of this file are subject to the Netscape Public
 * License Version 1.1 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of
 * the License at http://www.mozilla.org/NPL/
 *
 * Software distributed under the License is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * rights and limitations under the License.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is Netscape
 * Communications Corporation.  Portions created by Netscape are
 * Copyright (C) 1998 Netscape Communications Corporation. All
 * Rights Reserved.
 *
 * Contributor(s): 
 */

#include "nsISupports.idl"
#include "nsIRequest.idl"

interface nsIStreamListener;
interface nsIStreamProvider;
interface nsIInputStream;
interface nsIOutputStream;
interface nsIInterfaceRequestor;

[scriptable, uuid(fd01f9a4-d492-4cf8-b76e-160ffc8c01e8)]
interface nsITransport : nsISupports
{
    /**
     * Get security info for this transport.
     */
    readonly attribute nsISupports securityInfo;

    /**
     * Get/set notificationCallbacks for this transport.
     */
    nsIInterfaceRequestor getNotificationCallbacks();
    void setNotificationCallbacks(in nsIInterfaceRequestor callbacks,
                                  in unsigned long flags);

    /**
     * If the notificationCallbacks provide a nsIProgressEventSink
     * implementation, then progress is by default reported to the thread
     * that called setNotificationCallbacks.  The following flags provide
     * finer control over progress notifications:
     *
     * DONT_REPORT_PROGRESS - progress notifications are not sent.
     * DONT_PROXY_PROGRESS  - progress notifications can occur on any thread.
     */
    const unsigned long DONT_REPORT_PROGRESS = 1;
    const unsigned long DONT_PROXY_PROGRESS  = 2;

    /**
     * Open an input stream on this transport.
     *
     * @param offset - read starting at this offset
     * @param count  - read this many bytes (pass PRUint32(-1) if unlimited)
     * @param flags  - optional transport specific flags
     */
    nsIInputStream openInputStream(in unsigned long offset,
                                   in unsigned long count,
                                   in unsigned long flags);

    /**
     * Open an output stream on this transport.
     *
     * @param offset - write starting at this offset
     * @param count  - write no more than this many bytes (pass PRUint32(-1) if unlimited)
     * @param flags  - optional transport specific flags
     */
    nsIOutputStream openOutputStream(in unsigned long offset,
                                     in unsigned long count,
                                     in unsigned long flags);

    /**
     * Asynchronously read data from the transport.
     *
     * @param listener - notify this listener when data is available
     * @param ctxt     - opaque parameter passed to listener methods
     * @param offset   - read starting at this offset
     * @param count    - read this many bytes (pass PRUint32(-1) if unlimited)
     * @param flags    - optional transport specific flags
     */
    nsIRequest asyncRead(in nsIStreamListener listener,
                         in nsISupports ctxt, 
                         in unsigned long offset,
                         in unsigned long count,
                         in unsigned long flags);

    /**
     * Asynchronously write data to the transport.
     *
     * @param provider - notify this provider when data can be written
     * @param ctxt     - opaque parameter passed to provider methods
     * @param offset   - write starting at this offset
     * @param count    - write no more than this many bytes (pass PRUint32(-1) if unlimited)
     * @param flags    - optional transport specific flags
     */
    nsIRequest asyncWrite(in nsIStreamProvider provider,
                          in nsISupports ctxt, 
                          in unsigned long offset,
                          in unsigned long count,
                          in unsigned long flags);

    /**
     * Callbacks from asyncRead and asyncWrite may be proxied from a
     * background thread (if one exists) to the thread which initiated
     * the request.  This is the expected behavior of such a nsITransport
     * implementation.  A caller of asyncRead or asyncWrite can explicitly
     * ask the transport to not proxy the callback.  The caller must then
     * be prepared to handle callbacks on any thread.
     */
    const unsigned long DONT_PROXY_OBSERVER = 1 << 0;
    const unsigned long DONT_PROXY_LISTENER = 1 << 1;
    const unsigned long DONT_PROXY_PROVIDER = 1 << 1;

};

[scriptable, uuid(d7abf5a4-ce72-482a-9217-a219a905c019)]
interface nsITransportRequest : nsIRequest
{
    /**
     * Get the transport associated with this request.
     */
    readonly attribute nsITransport transport;
};