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

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* ***** BEGIN LICENSE BLOCK *****
 * Version: NPL 1.1/GPL 2.0/LGPL 2.1
 *
 * 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 the Initial Developer are Copyright (C) 1998
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or 
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the NPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the NPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

#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;
};